pppoe

pppoe [options]

-I interface
    Specifies the Ethernet interface to use for PPPoE (e.g., eth0). This option is often mandatory for establishing a connection.

-A
    Performs an auto-discovery of PPPoE Access Concentrators and prints their names and service names found. Useful for initial setup.

-S service_name
    Specifies the PPPoE service name to request during session establishment. Often required by ISPs.

-C AC_name
    Specifies the Access Concentrator name to connect to, overriding auto-discovery.

-s
    Runs pppoe in stand-alone (daemon) mode, forking into the background after connection establishment.

-k
    Keeps pppoe in the foreground; do not fork into the background. Useful for debugging or when running from a script.

-P pidfile
    Writes the Process ID (PID) of the pppoe daemon to the specified file when running in daemon mode.

-L logfile
    Appends all diagnostic output to the specified log file instead of standard error.

-T timeout
    Sets the maximum number of seconds to wait for a PPPoE session to be established.

-d
    Enables verbose debugging output, printing discovery and session details to the console or log file.

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

The pppoe command is a user-space client program for establishing a Point-to-Point Protocol over Ethernet (PPPoE) connection. It is commonly used to connect to Internet service providers (ISPs) that deliver services, primarily broadband DSL or cable, via PPPoE.

The pppoe client handles the PPPoE Discovery stage, which involves finding an access concentrator (AC) and establishing a PPPoE session. Once a session is successfully established, pppoe typically forks and executes the pppd (Point-to-Point Protocol daemon) to manage the actual PPP session, including authentication (e.g., PAP, CHAP), IP address assignment, and routing. It supports various options for specifying the Ethernet interface, service name, AC name, and debugging levels, making it a flexible tool for managing PPPoE-based network connectivity.

The pppoe client primarily handles the PPPoE discovery and session establishment. The actual PPP session management (authentication, IP assignment, routing) is handed off to the pppd daemon, which must be installed and correctly configured separately. Firewall rules might block PPPoE traffic (Ethertype 0x8863, 0x8864), preventing connection. Only one pppoe instance typically runs per interface for a full session.

The pppoe client handles the Ethernet-level PPPoE discovery and session establishment. However, the actual Point-to-Point Protocol (PPP) session, including user authentication (PAP/CHAP), IP address assignment, and routing, is managed by the pppd daemon. Therefore, successful PPPoE connectivity often requires proper configuration of pppd files such as /etc/ppp/chap-secrets, /etc/ppp/pap-secrets, and common options in /etc/ppp/options or /etc/ppp/options.pppoe.

A common workflow for establishing a PPPoE connection involves:
1. Discovery: Running sudo pppoe -A to find available Access Concentrators and service names.
2. Connection Initiation: Executing sudo pppoe -I <interface> -s [-S <service_name>] [-C <AC_name>] to initiate the PPPoE session. This typically forks and runs pppd.
3. Authentication: pppd then handles authentication with the ISP using credentials configured in /etc/ppp/*-secrets.
4. IP Assignment & Routing: Once authenticated, pppd obtains an IP address and configures network routing.

The pppoe command is a core component of the rp-pppoe (Roaring Penguin PPPoE) client package, developed by David F. Skoll. It emerged in the early 2000s as a crucial tool for Linux users to connect to DSL internet services that widely adopted the PPPoE protocol. Its robust and reliable implementation has made it a standard utility for broadband connectivity on Linux systems for decades.

pppd(8), pppoe-start(8), pppoe-stop(8), ifconfig(8), ip(8)