Tellsanguis/blog_tech
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

Ajout documentation OpenWRT et article freeze SSH, MTU et MSS clamping

Browse source 
- Ajouter documentation complète OpenWRT dans section Homelab actuel
- Créer article blog expliquant problème freeze SSH via tunnel GRE-TAP
- Documenter solutions MTU et MSS clamping pour tunnels réseau
- Ajouter traductions anglaises complètes pour nouveau contenu
This commit is contained in:
Tellsanguis 2025-12-02 12:43:12 +01:00
parent 8ed3805789
commit 87a2508769
22 changed files with 1086 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

189
i18n/en/docusaurus-plugin-content-blog/2025-12-02-ssh-freeze-mtu-mss-clamping.md Normal file
View file

@ -0,0 +1,189 @@
---
slug: ssh-freeze-mtu-mss-clamping
title: SSH Session Freeze, MTU and MSS Clamping
authors: [tellserv]
tags: [openwrt, gretap, ssh, mtu, networking]
image: /img/blog/2025-12-02-ssh-freeze-mtu/freeze_session_ssh.png
---
<p align="center">
<img src="/img/blog/2025-12-02-ssh-freeze-mtu/freeze_session_ssh.png" alt="Frozen SSH session" width="600" />
</p>
After deploying GREtap tunnels to extend my VLANs across my OpenWRT WiFi mesh, I encountered a frustrating issue: my SSH sessions would randomly freeze and require a complete restart. The cause? A classic MTU and fragmentation problem. Here's how MSS clamping solved the issue.
<!--truncate-->
## The Symptom: Freezing SSH Sessions
The problem was particularly annoying during remote administration:
- SSH sessions would work normally for a few minutes
- Then suddenly, the session would freeze completely
- No response, no error, just a frozen terminal
- Unable to type anything, even Ctrl+C wouldn't work
- Only solution: close the terminal and open a new connection
![Frozen SSH session](/img/blog/2025-12-02-ssh-freeze-mtu/freeze_session_ssh.png)
*SSH sessions would freeze without any error message.*
This behavior was intermittent but systematic: all sessions would eventually freeze after some time of use.
## Understanding MTU and Its Impact
### What is MTU?
**MTU (Maximum Transmission Unit)** represents the maximum size of a network packet that can be transmitted without fragmentation. On standard Ethernet, the default MTU is **1500 bytes**.
### The Problem with Tunnels
Tunneling protocols like GREtap add additional headers to each packet:
- **GRE header**: 4 bytes (tunnel protocol)
- **Outer IP header**: 20 bytes (for tunnel routing)
- **Inner Ethernet header**: 14 bytes (for transported traffic)
**Total GREtap overhead**: approximately **38 bytes**
This means for a **1500-byte** packet to transmit:
- Actual size after encapsulation: **1538 bytes**
- Ethernet MTU exceeded by: **38 bytes**
### WiFi Mesh Aggravates the Problem
On a WiFi mesh backhaul, the problem is even more pronounced:
- WiFi mesh adds its own headers
- WiFi fragmentation is less efficient than wired Ethernet
- Oversized packets can be silently dropped
- Result: connections that freeze without error messages
## The Diagnosis: MTU Problem Confirmed
Using `ping` with the **Don't Fragment** (DF) option, we can test the maximum accepted packet size.
On the GREtap interface configured with a default MTU of **1280 bytes**:
```bash
# Test with a 1253-byte packet
ping -M do -s 1253 192.168.100.2
# Result: FAILED (100% packet loss, "message too long, mtu=1280")
# Test with a 1252-byte packet
ping -M do -s 1252 192.168.100.2
# Result: SUCCESS (0% packet loss)
```
![MTU problem detected](/img/blog/2025-12-02-ssh-freeze-mtu/probleme_de_mtu.png)
*Ping tests showing failure at 1253 bytes and success at 1252 bytes with MTU 1280.*
The test reveals that the default MTU of **1280 bytes** is too restrictive. Slightly larger packets are fragmented or dropped, causing the SSH freezes.
## The Solution: MSS Clamping
### What is MSS Clamping?
**MSS (Maximum Segment Size)** is the maximum size of TCP data in a segment. **MSS clamping** is a technique that modifies TCP SYN packets (connection establishment) to announce a smaller MSS.
This forces both ends of the connection to:
- Negotiate a smaller TCP segment size
- Avoid fragmentation upstream
- Create packets that pass through the tunnel without issues
### Configuration in OpenWRT
MSS clamping configuration is done in OpenWRT's advanced firewall settings:
1. Navigate to **Network → Firewall**
2. Open the **Advanced Settings** tab
3. Enable **MSS clamping** for the relevant zones
![MSS clamping activation](/img/blog/2025-12-02-ssh-freeze-mtu/activer_mss_clamping.png)
**Option explanation**:
- **MSS clamping**: Enables automatic MSS recalculation based on interface MTU
- OpenWRT will automatically calculate: `MSS = MTU - 40` (TCP/IP headers)
## Validation Tests
After enabling MSS clamping and adjusting the MTU, I performed tests to confirm the problem is resolved.
### Tests with hping3 and tcpdump
To validate that MSS clamping is working correctly, I used **hping3** to send TCP SYN packets and **tcpdump** to capture and verify that the MSS is being modified:
```bash
# Send TCP SYN packets with hping3
hping3 -S -p 80 192.168.100.2
# Capture with tcpdump to verify MSS clamping
tcpdump -i gretap-gr -nn 'tcp[tcpflags] & tcp-syn != 0'
```
![Functional tests validated](/img/blog/2025-12-02-ssh-freeze-mtu/test_fonctionnel.png)
*Tcpdump capture showing MSS clamping in action: packets with MSS 1500 are automatically modified to use MSS 1240.*
Tests confirm that MSS clamping is working correctly and that SSH sessions no longer freeze, even with large data transfers.
## Manual MTU Configuration
Additionally to MSS clamping, I also manually adjusted the MTU on the GREtap interface:
**On both routers**:
1. **Network → Interfaces → [GREtap Interface]**
2. **Advanced Settings**:
- **Override MTU**: `1450` or `1400`
Why not use the theoretical optimal MTU of 1462?
- WiFi mesh MTU: 1500 bytes
- GREtap overhead: 38 bytes
- Theoretical optimal MTU: 1500 - 38 = **1462 bytes**
However, I chose an MTU of **1450 or 1400** to have a **safety margin**, especially to ensure WiFi mesh stability which can add variable additional headers.
## Understanding MSS Clamping in Detail
MSS clamping works by modifying **TCP SYN** packets during connection establishment:
1. **Client** sends SYN with MSS=1460 (default Ethernet value)
2. **Router with MSS clamping** intercepts the packet
3. **Router** recalculates: Optimal MSS = Interface MTU - 40 = 1462 - 40 = **1422**
4. **Router** modifies the SYN packet to announce MSS=1422
5. **Server** responds with MSS=1422 or less
6. **Result**: the entire TCP connection will use segments of maximum 1422 bytes
With an MSS of 1422 bytes:
- TCP segment size: 1422 bytes
- + TCP header: 20 bytes
- + IP header: 20 bytes
- **= Total IP packet: 1462 bytes**
This 1462-byte packet:
- Enters the GREtap tunnel
- + GREtap overhead: 38 bytes
- **= Final packet: 1500 bytes**
The final 1500-byte packet fits perfectly within the 1500-byte Ethernet MTU. No fragmentation needed.
## Conclusion
MSS clamping is an elegant solution to resolve MTU issues on tunnels:
- **Transparent**: works automatically without client configuration
- **Effective**: completely avoids fragmentation
- **Performant**: no negative performance impact
- **Standard**: supported by all modern routers and firewalls
If you deploy GREtap tunnels (or any other tunnel type) on your network infrastructure, remember to:
1. Calculate the optimal MTU by subtracting the protocol overhead
2. Manually configure the MTU on tunnel interfaces
3. Enable MSS clamping in your firewall
For more details on the complete configuration of GREtap tunnels with OpenWRT, see the full article: [GREtap Tunnels for VLANs](/docs/openwrt/gretap-vlan).
SSH sessions are now stable, even under load. No more freezes. Mission accomplished.

122
i18n/en/docusaurus-plugin-content-docs/current/openwrt/backhaul-wifi-mesh.md Normal file
View file

@ -0,0 +1,122 @@
---
sidebar_position: 2
title: WiFi Mesh Backhaul with 802.11s
---
# WiFi Mesh Backhaul with 802.11s
This guide explains how to create a WiFi backhaul between two OpenWRT routers using the 802.11s (mesh point) protocol.
## Objective
Create a mesh WiFi link between two OpenWRT routers to extend the network without an Ethernet cable. The second router will be configured as a "Dumb AP" and will communicate with the main router via a secure mesh backhaul.
## Prerequisites
- Two routers with OpenWRT installed
- SSH or LuCI web interface access on both routers
- A configured main router (with active DHCP and firewall)
## Step 1: Configuring the Second Router as a Dumb AP
The second router must be transformed into a "Dumb AP" (basic Access Point without network services). There is an automatic script for this configuration, but we will detail the manual method via the LuCI interface.
### Automatic Script (Optional)
For automatic configuration, you can use **OneMarcFifty**'s script available on [GitHub - onemarcfifty/openwrt-mesh](https://github.com/onemarcfifty/openwrt-mesh).
### Manual Configuration via LuCI
You need to **disable** the following services on the second router:
1. **Firewall**: **System → Startup** → Disable `firewall`
2. **DNS**: **Network → DHCP and DNS** → Uncheck "DNS server"
3. **DHCP Server**: **Network → Interfaces → LAN → DHCP Server** → Check "Ignore interface"
These services are not necessary because the main router handles security, DNS, and IP address distribution.
### LAN Interface Configuration
Configure the second router's LAN interface to be on the **same subnet** as the main router:
1. Go to **Network → Interfaces → LAN**
2. Configure the following parameters:
- **Protocol**: DHCP client (recommended) or Static address
- If Static: **IPv4 address**: `.2` on the subnet (example: if the main router is at `192.168.1.1`, set `192.168.1.2`)
![DHCP configuration of br-lan interface](/img/openwrt/interface_br-lan_dhcp.png)
:::tip Configuration Backup
Before modifying the LAN interface, note the current IP or configure a backup interface to be able to access the router in case of problems.
![Backup interface](/img/openwrt/sauvetage_interface.png)
:::
## Step 2: Configuring the 802.11s Mesh Network
The 802.11s protocol allows creating a native WiFi mesh network. Both routers will use this protocol to establish the backhaul.
### Mesh Parameters
Both routers must have **exactly the same** following parameters:
1. **WiFi Mode**: Mesh Point
2. **Mesh ID**: unique identifier for your mesh (same value on both routers)
3. **Network Interface**: create a dedicated interface for the mesh (example: `mesh0`)
4. **Security**: WPA3-SAE (Personal) recommended
5. **Password**: strong and random password
### Generating a Secure Password
Use this command to generate a strong random password:
```bash
openssl rand -base64 32
```
Or from OpenWRT:
```bash
dd if=/dev/urandom bs=1 count=32 2>/dev/null | base64
```
### Configuration via LuCI
1. Go to **Network → Wireless**
2. Select the WiFi interface to use for the mesh (usually radio0 or radio1)
3. Configure the following parameters:
![WiFi mesh backhaul configuration](/img/openwrt/config_backhaul_wifi.png)
**Essential Parameters**:
- **Mode**: Mesh Point (802.11s)
- **Mesh ID**: your mesh identifier (identical on both routers)
- **Network**: create or select a dedicated network interface for the mesh
- **Encryption**: WPA3-SAE
- **Key**: the previously generated password
:::warning Parameter Synchronization
Both routers must have **exactly** the same Mesh ID and the same password, otherwise they will not be able to establish the mesh connection.
:::
### Network Interface for the Mesh
Create a dedicated network interface for the mesh:
1. **Network → Interfaces → Add new interface**
2. **Name**: `mesh0` (or any other descriptive name)
3. **Protocol**: Static address or DHCP client
4. **Device**: select the created mesh device (usually `mesh0`)
This interface will serve as the basis for the GREtap tunnel in the next section.
## Verification
After configuration, verify that:
1. The second router obtains an IP on the same subnet as the main router
2. Both routers can ping each other
3. The mesh interface is active and connected (verifiable in **Network → Wireless**)
4. The mesh backhaul is established and stable
## Next Step
Once the mesh backhaul is configured, you can proceed to [GREtap configuration to extend VLANs](./gretap-vlan.md) through this mesh link.

210
i18n/en/docusaurus-plugin-content-docs/current/openwrt/gretap-vlan.md Normal file
View file

@ -0,0 +1,210 @@
---
sidebar_position: 3
title: GREtap Tunnels for VLANs
---
# GREtap Tunnels for VLANs Across the Mesh
This guide explains how to extend VLANs across the WiFi mesh backhaul using GREtap tunnels.
## Prerequisites
- WiFi mesh backhaul configured according to the [previous guide](./backhaul-wifi-mesh.md)
- Both routers must be able to communicate via the mesh interface
- Access to the LuCI interface on both routers
## Why GREtap Instead of BATMAN-adv?
For a mesh network consisting of **only two routers**, GREtap is preferable to BATMAN-adv for several reasons:
### Advantages of GREtap in This Scenario
1. **Point-to-Point Sufficient**: With two routers, a simple point-to-point tunnel is sufficient. BATMAN-adv is designed for complex mesh topologies with many nodes and redundant paths.
2. **Less Overhead**: GREtap has lower protocol overhead than BATMAN-adv. With only two nodes, the advanced mesh routing features of BATMAN are not necessary.
3. **Configuration Simplicity**: GREtap is simpler to configure and debug. No need to manage mesh routing tables, path metrics, or route selection algorithms.
4. **Predictability**: Traffic always takes the same path (the direct tunnel). No dynamic route changes.
5. **Native Support**: GREtap is widely supported and documented in OpenWRT without requiring complex additional kernel modules.
:::info BATMAN-adv: When to Use It?
BATMAN-adv becomes interesting when you have:
- 3 or more mesh nodes
- Multiple possible paths between nodes
- Need for redundancy and automatic failover
- Dynamic mesh topology with mobile nodes
:::
## Installing Required Packages
Install the necessary package on **both routers**:
```bash
opkg update
opkg install luci-proto-gre
```
Or via the LuCI interface: **System → Software**, search for and install `luci-proto-gre`.
## Configuring the GREtap Tunnel
### Step 1: Create the GREtap Interface
On **both routers**, create a new GREtap interface:
1. Go to **Network → Interfaces → Add new interface**
2. Configure the basic parameters
**Basic Parameters**:
- **Name**: short name (example: `gr`)
- **Protocol**: GRETAP (Ethernet over GRE)
:::danger Interface Name Length Limitation
OpenWRT automatically creates the interface with the `gretap-` prefix. For example, if you name your interface `trunk`, OpenWRT will create `gretap-trunk`.
**Problem**: To pass VLANs, the notation will be `gretap-trunk.100`, which is **16 characters** and exceeds the limit!
**Problematic Example**:
- Interface named `trunk` → Device created: `gretap-trunk` (13 characters)
- VLAN 100 → `gretap-trunk.100` (16 characters) ❌ **TOO LONG**
**Solution**: Use a **very short** name like `gr`, `t`, or `g`.
- Interface named `gr` → Device created: `gretap-gr` (9 characters)
- VLAN 100 → `gretap-gr.100` (13 characters) ✅ **OK**
:::
:::info Origin of This Limitation
Network interface names under Linux are stored in a structure that uses a 16-byte array. This array includes the null terminator `\0`, so the maximum length of a network interface name is **15 characters** (16 - 1 = 15).
:::
**Tunnel Parameters (General Settings)**:
- **Remote IPv4 address or FQDN**: IP of the other router on the mesh interface
- **Local IPv4 address**: IP of this router on the mesh interface
![GREtap interface configuration](/img/openwrt/interface-gretap.png)
**Advanced Options (Advanced Settings)**:
It is important to configure the advanced options correctly:
- ⬜ **Use TTL on tunnel interface**: leave unchecked
- ⬜ **Use PMTU discovery**: leave unchecked (equivalent to **Don't fragment**)
- ⬜ **Default gateway**: UNCHECK this option (important!)
- **Bind interface**: select the mesh interface (for example `lan`)
![GREtap advanced parameters configuration](/img/openwrt/interface_gretap_parametresavance.png)
:::tip Why Uncheck These Options?
- **PMTU discovery / Don't fragment**: WiFi mesh traffic may require fragmentation. Allowing fragmentation avoids packet loss.
- **Default gateway**: The GREtap tunnel should not become the router's default gateway.
:::
## Extending VLANs Through the Tunnel
### Principle
To pass a VLAN through the GREtap tunnel, you need to create a **bridge device** that contains:
- The local physical port or VLAN interface
- The corresponding GREtap VLAN port
The notation used for a GREtap VLAN port is: `@<gretap_device_name>.<vlan_number>`
**Example**: For VLAN 100 with a tunnel named `gr` (device: `gretap-gr`) → `@gretap-gr.100`
### Configuration on the Main Router
#### Step 1: Create the Bridge Device for the VLAN
1. Go to **Network → Interfaces → Devices → Add device configuration**
2. Create a **Bridge device**:
**Bridge Configuration**:
- **Device type**: Bridge device
- **Device name**: `br-lab` (or descriptive name for your VLAN)
- **Bridge ports**: Add the following ports:
- The local physical port or VLAN (example: `lan3` for a physical port)
- The GREtap VLAN port: `@gretap-gr.100` (adapt according to your device and VLAN number)
![Bridge device with GREtap port](/img/openwrt/bridge_device_lab_avec_port_gretap.png)
#### Step 2: Create the Network Interface for the VLAN
1. **Network → Interfaces → Add new interface**
2. Configure the interface:
**Parameters (General Settings)**:
- **Name**: `LAB` (or descriptive name)
- **Protocol**: Static address
- **Device**: Select the previously created bridge (`br-lab`)
- **IPv4 address**: This router's IP address on the VLAN (example: `192.168.100.1`)
- **IPv4 netmask**: The VLAN's netmask (example: `255.255.255.0`)
![VLAN interface with bridge as device](/img/openwrt/interface_vlan_lab_avec_bridge_en_device.png)
**DHCP Server (DHCP Server)**:
Configure the DHCP server for this VLAN to distribute IPs to clients:
![VLAN DHCP configuration](/img/openwrt/interface_vlan_lab_dhcp_sur_routeur_maitre.png)
**Firewall Settings**:
Assign the interface to an appropriate firewall zone (example: `homelab_zone` or create a new zone):
![Firewall zone configuration](/img/openwrt/interface_vlan_lab_firewallzone.png)
:::tip Static DHCP Leases
Once the Dumb AP retrieves an IP via DHCP on this VLAN, you can configure a **static DHCP lease** to assign it a fixed IP.
Example: set the Dumb AP to IP `.2` on each VLAN for consistent configuration (example: `192.168.100.2`).
:::
Repeat this configuration for each VLAN to extend through the tunnel.
### Configuration on the Dumb AP
On the second router (Dumb AP), the VLAN interfaces must be configured as **DHCP clients** to automatically retrieve an IP on each VLAN.
1. **Network → Interfaces → Add new interface**
2. Configure the interface:
- **Name**: `vlan100` (or descriptive name)
- **Protocol**: DHCP client
- **Device**: `@gretap-gr.100` (the GREtap VLAN port)
The Dumb AP will automatically retrieve an IP address from the main router's DHCP server on this VLAN.
### Multi-VLAN Configuration Example
**Typical Configuration**:
- VLAN 10 (Management) → `@gretap-gr.10`
- VLAN 100 (Homelab) → `@gretap-gr.100`
- VLAN 200 (IoT) → `@gretap-gr.200`
Each VLAN crosses the GREtap tunnel transparently and in isolation.
## Verification and Testing
### Connectivity Tests
From the Dumb AP, test connectivity on each VLAN:
```bash
# Ping to VLAN 100 gateway
ping -I vlan100 192.168.100.1
# Verify obtaining an IP via DHCP
ip addr show dev gretap-gr.100
```
From the main router, verify that the Dumb AP appears in the DHCP leases:
- **Network → Interfaces → LAB → DHCP Server → Active DHCP Leases**
## Conclusion
With GREtap, you can effectively extend your VLANs across a WiFi mesh backhaul between two OpenWRT routers. This solution offers a good compromise between simplicity, performance, and functionality for point-to-point topologies.
For more complex mesh networks with 3 or more nodes, consider using BATMAN-adv which offers more advanced mesh routing features.

16
i18n/en/docusaurus-plugin-content-docs/current/openwrt/index.md Normal file
View file

@ -0,0 +1,16 @@
---
sidebar_position: 1
title: OpenWRT
---
# OpenWRT
The OpenWrt Project is a Linux-based operating system designed for embedded devices (primarily routers). Instead of being a fixed and locked operating system, OpenWrt offers a fully customizable operating system through a package manager. This allows you to break free from the applications and configuration installed by the manufacturer, enabling you to customize your device through the addition and use of packages that bring new functionalities.
For developers, OpenWrt is the ideal environment to build an application without having to build an entire firmware around it. For users, OpenWrt allows total customization, as well as the possibility of using the device for purposes never originally envisioned.
## Resources
- [Official OpenWRT Website](https://openwrt.org/start)
- [OpenWRT Documentation](https://openwrt.org/docs/start)
- [OpenWRT Wiki](https://openwrt.org/start)