---
name: "pppoe-relay"
section: "8"
platform: "linux"
package: "rp-pppoe"
version: "4.0-6"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/pppoe-relay"
---

# pppoe-relay(8)

user-space PPPoE relay agent.

## NAME

pppoe-relay - user-space PPPoE relay agent.

## SYNOPSIS

**pppoe-relay \[*options*\]**

## DESCRIPTION

**pppoe-relay** is a user-space relay agent for PPPoE (Point-to-Point Protocol over Ethernet) for Linux.  **pppoe-relay** works in concert with the **pppoe** client and **pppoe-server** server.  See the OPERATION section later in this manual for details on how **pppoe-relay** works.

## OPTIONS

- **-S *interface***

  Adds the Ethernet interface *interface* to the list of interfaces managed by **pppoe-relay**.  Only PPPoE servers may be connected to this interface.

- **-C *interface***

  Adds the Ethernet interface *interface* to the list of interfaces managed by **pppoe-relay**.  Only PPPoE clients may be connected to this interface.

- **-B *interface***

  Adds the Ethernet interface *interface* to the list of interfaces managed by **pppoe-relay**.  Both PPPoE clients and servers may be connected to this interface.

- **-n *num***

  Allows at most *num* concurrent PPPoE sessions.  If not specified, the default is 5000.  *num* can range from 1 to 65534.

- **-i *timeout***

  Specifies the session idle timeout.  If both peers in a session are idle for more than *timeout* seconds, the session is terminated. If *timeout* is specified as zero, sessions will never be terminated because of idleness.

  Note that the idle-session expiry routine is never run more frequently than every 30 seconds, so the timeout is approximate.  The default value for *timeout* is 600 seconds (10 minutes.)

- **-F**

  The **-F** option causes **pppoe-relay** *not* to fork into the background; instead, it remains in the foreground.

- **-h**

  The **-h** option prints a brief usage message and exits.

## OPERATION

**pppoe-relay** listens for incoming PPPoE PADI frames on all interfaces specified with **-B** or **-C** options.  When a PADI frame appears, **pppoe-relay** adds a Relay-Session-ID tag and broadcasts the PADI on all interfaces specified with **-B** or **-S** options (except the interface on which the frame arrived.)

Any PADO frames received are relayed back to the client which sent the PADI (assuming they contain valid Relay-Session-ID tags.)  Likewise, PADR frames from clients are relayed back to the matching access concentrator.

When a PADS frame is received, **pppoe-relay** enters the two peers' MAC addresses and session-ID's into a hash table.  (The session-ID seen by the access concentrator may be different from that seen by the client; **pppoe-relay** must renumber sessions to avoid the possibility of duplicate session-ID's.)  Whenever either peer sends a session frame, **pppoe-relay** looks up the session entry in the hash table and relays the frame to the correct peer.

When a PADT frame is received, **pppoe-relay** relays it to the peer and deletes the session entry from its hash table.

If a client and server crash (or frames are lost), PADT frames may never be sent, and **pppoe-relay**'s hash table can fill up with stale sessions. Therefore, a session-cleaning routine runs periodically, and removes old sessions from the hash table.  A session is considered "old" if no traffic has been seen within *timeout* seconds.  When a session is deleted because of a timeout, a PADT frame is sent to each peer to make certain that they are aware the session has been killed.

## EXAMPLE INVOCATIONS

```
pppoe-relay -C eth0 -S eth1
```

The example above relays frames between PPPoE clients on the eth0 network and PPPoE servers on the eth1 network.

```
pppoe-relay -B eth0 -B eth1
```

This example is a transparent relay -- frames are relayed between any mix of clients and servers on the eth0 and eth1 networks.

```
pppoe-relay -S eth0 -C eth1 -C eth2 -C eth3
```

This example relays frames between servers on the eth0 network and clients on the eth1, eth2 and eth3 networks.

## AUTHORS

**pppoe-relay** was written by Dianne Skoll \<dianne@skoll.ca\>.

The **pppoe** home page is *https://dianne.skoll.ca/projects/rp-pppoe/*.

## SEE ALSO

[pppd(8)](/pppd/8.md), [pppoe(8)](/pppoe/8.md), [pppoe-sniff(8)](/pppoe-sniff/8.md), [pppoe-server(8)](/pppoe-server/8.md)