pppoe-server

pppoe-server [options]

-I interface
    Specifies the Ethernet interface on which pppoe-server should listen for PPPoE discovery packets. This is a mandatory option.

-T timeout
    Sets the timeout in seconds for PADI packets. Sessions that don't transition from PADI to PADR within this time will be dropped.

-S service_name
    Specifies a service name that the AC will offer. Clients requesting this specific service name will be served. If omitted, the server will offer any service.

-p plugin_path
    Specifies the path to a shared library plugin to be loaded by the server. This is typically used for advanced features or custom session management.

-L local_IP
    Sets the local IP address for the PPP interface created for each session. This is the server-side IP address.

-R remote_IP_range
    Defines a range of remote IP addresses (e.g., '192.168.1.100-192.168.1.200') from which pppd will allocate addresses to clients. Alternatively, a single IP or 'dynamic' can be used.

-C ac_name
    Sets the Access Concentrator name to be advertised in PADO packets. Defaults to the hostname.

-s
    Causes pppoe-server to spawn the pppoed helper program for each session. This is generally the default and recommended behavior for proper session management.

-u
    Instructs pppoe-server to use its own built-in pppoed helper for session handling, rather than an external one. This is typically the default.

-x max_sessions
    Sets the maximum number of concurrent PPPoE sessions the server will allow. New sessions will be rejected once this limit is reached.

-o pppd_options_file
    Specifies an additional options file to be passed to each pppd process spawned by the server. This allows for custom pppd configurations.

-k
    Instructs the server to keep the pppd process running even if it becomes unresponsive or exits unexpectedly. Use with caution.

-r
    Restricts sessions to one per MAC address. If a client with an existing session attempts to connect again, the old session will be terminated.

-d
    Enables debugging output. Increases verbosity, helpful for troubleshooting.

-V
    Prints the version number of the pppoe-server and exits.

The pppoe-server command acts as a PPPoE (Point-to-Point Protocol over Ethernet) Access Concentrator (AC). It listens for PPPoE discovery packets (PADI) from clients on a specified Ethernet interface. Upon receiving a discovery request, it offers a service (PADO) and, if accepted by the client (PADR), establishes a PPPoE session (PADS).

Once a session is established, pppoe-server spawns a pppd (Point-to-Point Protocol daemon) process for each client. This pppd instance then handles the actual PPP negotiation, authentication (typically via PAM, RADIUS, or a local `chap-secrets` file), and IP address assignment. It essentially bridges the Ethernet frames from the PPPoE session into a PPP link, allowing clients to obtain IP addresses and access network resources, commonly the internet.

It's widely used by ISPs and network administrators to provide internet access over Ethernet-based infrastructure, such as ADSL or fiber modems operating in bridge mode, allowing multiple clients to connect and authenticate centrally.

pppoe-server relies heavily on the pppd daemon for session management, authentication, and IP assignment. Proper configuration of pppd, including authentication methods (e.g., PAM, RADIUS, or /etc/ppp/chap-secrets) and IP address pools, is crucial for a functional server.

Firewall rules are essential to protect the server and correctly route traffic. Ensure that the specified Ethernet interface is not already in use by other services that might conflict with PPPoE.

Scaling to a very large number of concurrent sessions may require careful system tuning and resource allocation.

pppoe-server itself does not handle user authentication or IP address allocation directly. Instead, it delegates these critical functions to the pppd (Point-to-Point Protocol daemon) process it spawns for each session. pppd can then be configured to use various authentication mechanisms, such as PAM (Pluggable Authentication Modules), RADIUS (Remote Authentication Dial-In User Service), or local files like /etc/ppp/chap-secrets and /etc/ppp/pap-secrets. Similarly, IP address assignment is handled by pppd based on its configuration, often using the specified local and remote IP options or a RADIUS server.

The primary and essential dependency for pppoe-server to function correctly is the pppd (Point-to-Point Protocol daemon). pppoe-server acts as a front-end to negotiate the PPPoE session, but the actual PPP link layer, authentication, and IP management are handled by a dedicated pppd instance for each connected client. Ensure pppd is installed and properly configured on your system.

The pppoe-server command is part of the rp-pppoe (Roaring Penguin PPPoE) package, which was one of the earliest and most widely adopted open-source implementations of PPPoE for Linux. Developed by Roaring Penguin Software, it gained prominence in the early 2000s as ADSL internet access became widespread, providing a robust and flexible solution for both client and server-side PPPoE operations. Its design emphasizes modularity by leveraging the existing pppd daemon for PPP session handling.

pppd(8), pppoe(8), pppoed(8), rp-pppoe.conf(5)