# Peering via Layer 2 Tunnel

Layer 2 tunnels encapsulate Ethernet frames, creating a virtual bridge between networks. Use this when you need to carry VLAN-tagged traffic or extend a broadcast domain.

> **Layer 2 Tunnel Overview**
>
> In all examples below, replace placeholder values with your actual configuration:
>
> * `{name}` - Tunnel interface name
> * `{yourside ip}` - Your public IP address
> * `{ourside ip}` - Our endpoint IP address
> * `{your tunnel ip cidr}` - Your tunnel IP/subnet
> * `{vni}` - VxLAN Network Identifier (24-bit value)

## Protocol Choice

## GRETAP

**GRETAP** (GRE Bridging) operates at Layer 2, encapsulating Ethernet frames inside GRE. Use this when you need a transparent L2 bridge over the tunnel.

### Shell

```shell
ip link add {name} type gretap local {yourside ip} remote {ourside ip} ttl 255
ip addr add {your tunnel ip cidr} dev {name}
ip link set dev {name} up
```

### Netplan

1. Create a Netplan configuration file:

```yaml title="/etc/netplan/10-{name}.yaml"
network:
  version: 2
  tunnels:
    { name }:
      mode: gretap
      local: { yourside ip }
      remote: { ourside ip }
      ttl: 255
      addresses:
        - { your tunnel ip cidr }
```

2. Apply the configuration:

```sh
netplan apply
```

### Systemd

1. Create the `.netdev` file:

```ini title="/etc/systemd/network/10-{name}.netdev"
[NetDev]
Name = {name}
Kind = gretap

[Tunnel]
Local  = {yourside ip}
Remote = {ourside ip}
TTL    = 255
```

2. Configure the tunnel IP address:

```ini title="/etc/systemd/network/10-{name}.network"
[Match]
Name = {name}

[Network]
Address = {your tunnel ip cidr}
```

3. Apply the configuration:

```sh
systemctl restart systemd-networkd
```

## VxLAN

**VxLAN** (Virtual Extensible LAN) is a Layer 2 overlay protocol that encapsulates Ethernet frames in UDP. It's designed for large-scale multi-tenant environments and software-defined networks.

> The default VxLAN destination port is **4789** (IANA-assigned). The VNI is a 24-bit identifier (0-16777215).

### Shell

```shell
ip link add {name} type vxlan local {yourside ip} remote {ourside ip} dstport 4789 id {vni} ttl 255
ip addr add {your tunnel ip cidr} dev {name}
ip link set dev {name} up
```

### Netplan

> Netplan's VxLAN support requires **netplan ≥ 0.106** (Ubuntu 23.04+).

1. Create a Netplan configuration file:

```yaml title="/etc/netplan/10-{name}.yaml"
network:
  version: 2
  tunnels:
    { name }:
      mode: vxlan
      local: { yourside ip }
      remote: { ourside ip }
      port: 4789
      id: { vni }
      ttl: 255
      addresses:
        - { your tunnel ip cidr }
```

2. Apply the configuration:

```sh
netplan apply
```

### Systemd

1. Create the `.netdev` file:

```ini title="/etc/systemd/network/10-{name}.netdev"
[NetDev]
Name = {name}
Kind = vxlan

[VXLAN]
VNI             = {vni}
Local           = {yourside ip}
Remote          = {ourside ip}
DestinationPort = 4789
TTL             = 255
```

2. Configure the tunnel IP address:

```ini title="/etc/systemd/network/10-{name}.network"
[Match]
Name = {name}

[Network]
Address = {your tunnel ip cidr}
```

3. Apply the configuration:

```sh
systemctl restart systemd-networkd
```

## GRETAP vs VxLAN

| Feature            | GRETAP           | VxLAN               |
| ------------------ | ---------------- | ------------------- |
| Protocol           | IP Protocol 47   | UDP port 4789       |
| Encapsulation      | GRE header       | UDP + VxLAN header  |
| MTU overhead       | 38 bytes         | 50 bytes            |
| NAT traversal      | Limited          | Better (UDP-based)  |
| Multi-cast support | Yes              | Yes                 |
| Use case           | Simple L2 bridge | Data center overlay |

## Considerations

> **Important Notes for Layer 2 Tunneling**
>
> * **MTU**: Layer 2 tunnels add significant overhead. Reduce your MTU accordingly (typically 1450-1476 bytes).
> * **Broadcast domain**: The tunnel extends your broadcast domain, which may cause issues with certain protocols.
> * **Spanning Tree**: Be cautious with STP over tunnels-consider using RSTP or disabling STP on the tunnel interface.
> * **Performance**: Layer 2 tunneling has more overhead than Layer 3. Use only when necessary.

## Next Steps

Once you have configured the tunnel:

1. Verify connectivity using `ping` or `traceroute`
2. Configure your BGP daemon (BIRD, FRR, etc.) to use the tunnel interface
3. [Contact us](/docs/about#contact-us) to finalize the peering session

> **Prefer Layer 3?** For most peering scenarios, Layer 3 tunnels (WireGuard, GRE) are recommended due to lower overhead and better performance.

---

## License and attribution

- **Canonical source:** [View the human-readable HTML page](https://hatsnet.io/docs/peering/via-layer2-tunnel).
- **Original documentation:** © Hats Network Inc., licensed under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/).
- **Full terms:** [Content and Data License](https://hatsnet.io/docs/legal/content-and-data-license) — includes attribution requirements, third-party material, trademarks, source code and other exclusions.