FreeBSD PPPoE Operations: Profiles, Routes, and Link Diagnostics

FreeBSD’s base-system ppp(8) implements user-space PPP and supports PPP over Ethernet (PPPoE). In this model, PPP negotiation runs in a process and uses a tun(4) interface for the network-layer connection. The Ethernet NIC provides access to the provider’s PPPoE service; it is not itself the routed interface that receives the negotiated IP configuration.

This article focuses on FreeBSD as a PPPoE client. The provider’s modem/ONT mode, credentials, service tag, and address policy are external inputs. Confirm those values with the provider rather than adapting an unrelated ADSL or dial-up recipe. A successful Ethernet link only proves that the physical path is up; PPPoE discovery, session negotiation, authentication, IPCP/IPv6CP, route installation, DNS, and application traffic are separate stages.

Collect provider details and identify the WAN NIC

Before editing configuration, obtain the actual Ethernet interface connected to the bridged modem/ONT, the service name/tag if required, authentication method and account, whether the provider assigns dynamic or static addressing, DNS policy, expected MTU, and whether a default route should be installed. Confirm whether the modem is in bridge or router mode; running PPPoE behind a device that already terminates PPP can create double NAT or simply fail to discover a peer.

Identify the correct NIC by MAC address and link state. Do not infer the WAN interface from em0 or igb0 naming alone. Inspect current addresses and routes so that a PPP profile does not unexpectedly replace a management or LAN default route.

ifconfig -a
ifconfig -m igb1
ifconfig igb1
netstat -rn

Replace igb1 with the verified provider-facing interface. The Ethernet link should be up, but avoid configuring a normal DHCP client and PPPoE as competing owners of the same provider link unless the provider explicitly requires a dual-mode arrangement. Keep LAN addressing on its own interface and document which path should carry the host’s default route.

Define a profile in `/etc/ppp/ppp.conf`

The user-ppp configuration uses labels. The default: section is executed first; a named provider section adds or overrides settings when selected. Configuration lines under a label must be indented, while each label begins at column one. FreeBSD’s Handbook shows this profile structure and the PPPoE:<interface> device notation.

default:
  set log Phase LCP IPCP CCP tun
  set redial 30 0

provider:
  set device PPPoE:igb1
  set authname REPLACE_WITH_PROVIDER_LOGIN
  set authkey REPLACE_WITH_PROVIDER_SECRET
  set dial
  set login
  set ifaddr 10.0.0.1/0 10.0.0.2/0
  add default HISADDR

The authentication values are placeholders and must be replaced with provider-approved credentials. Protect the configuration according to the local system’s credential-handling policy and do not paste secrets into tickets or shell history. The example’s private set ifaddr values are negotiation hints from the Handbook pattern, not public addresses to assign manually. The peer may negotiate the actual address. add default HISADDR requests a default route through the negotiated peer; include it only if this PPP connection should own the host’s default route. Here, set redial 30 0 asks for a 30-second retry interval with no finite attempt cap; choose a finite limit if provider policy or the service owner requires one. Do not set set reconnect ... 0 expecting retries: in ppp(8), zero reconnect attempts means no reconnect attempts.

If the provider requires a service tag, use the documented form PPPoE:igb1:TAG for set device, with the exact tag value supplied by the ISP. A guessed tag can prevent discovery even though carrier and Ethernet link tests pass. Static addressing needs a provider-specific profile; do not retain the dynamic example and assume it matches a reserved/static account.

The example enables phase-level logging useful during setup. Reduce verbosity once the connection is stable and ensure syslog handles the PPP facility as intended. Avoid logging authentication secrets. Keep a copy of the previous profile before edits so that a failed startup can be rolled back without reconstructing credentials from memory.

Start and persist the connection

Test the provider profile in a maintenance session before enabling it at boot. The Handbook’s PPPoE example starts ppp with -ddial; this mode maintains a persistent connection and retries after a disconnect according to the configured redial behavior. The rc settings can launch the named profile during startup:

ppp -ddial provider

After a successful manual test, configure the service:

sysrc ppp_enable="YES"
sysrc ppp_mode="ddial"
sysrc ppp_profile="provider"
sysrc ppp_nat="NO"
service ppp start

ppp_nat is a separate policy choice. Enable PPP’s built-in NAT only when this host is intentionally providing address translation for an internal LAN and the corresponding routing/firewall design has been reviewed. A host-only PPPoE client usually does not need it. Do not enable NAT as a generic PPPoE troubleshooting step; it changes packet forwarding behavior and is not required to negotiate the link.

Check service status and process state after startup. Confirm that tun0 or the selected tunnel unit exists, has the negotiated address, and is up. Verify that the default route changes only if expected. ppp can update resolver configuration when DNS negotiation is enabled; coordinate that behavior with local Unbound, DHCP, VPN, and any resolvconf integration so that one source does not overwrite another unexpectedly.

Follow the negotiation state machine

Troubleshoot in protocol order. First confirm Ethernet carrier and the correct physical NIC. Next, observe PPPoE discovery: the client must find a provider access concentrator and establish a session. Then confirm Link Control Protocol negotiation, provider authentication, and network-layer configuration such as IPCP or IPv6CP. Finally verify routes, DNS, MTU, and application traffic.

ppp(8) supports logging for phases including Phase, LCP, IPCP, IPV6CP, Chat, tun, and commands; exact messages vary by provider and release. Increase logging only for the failing stage and capture a short interval. A missing PADO/discovery response points earlier in the path than an authentication rejection; an established LCP session with no IPCP address points to a later stage. Use provider support with timestamps and redacted logs when the failing stage is upstream.

The following checks separate local interface, tunnel, route, and DNS state:

ifconfig igb1
ifconfig tun0
netstat -rn -f inet
sockstat -4 -l
drill FreeBSD.org

tun0 is an example unit; inspect ifconfig -a for the actual one. The presence of an interface is not proof of a negotiated, usable route. Test a known provider peer or Internet address by IP before blaming DNS, then test name resolution through the intended resolver. A firewall rule on the Ethernet interface may need to distinguish discovery/PPP traffic from the IP traffic that later traverses the tunnel; follow the configured firewall’s documented PPPoE behavior.

MTU, fragmentation, and application symptoms

PPPoE adds framing overhead compared with plain Ethernet. The usable IP MTU depends on the provider, NIC, modem, and entire path. Do not hard-code a universal value or treat one successful small ping as proof that large packets work. Obtain the supported MTU/MRU from the provider and test representative packet sizes to a destination that responds reliably. If small requests work but large TLS transfers, VPN packets, or file copies stall, investigate MTU and path-MTU discovery before changing authentication or redial policy.

Keep MSS clamping and firewall policy as deliberate network controls, not arbitrary trial values. Verify whether the path supports larger frames or an RFC 4638-style 1500-byte PPP MTU before attempting jumbo behavior. Every Ethernet segment, including modem, switch, and upstream provider path, must support the intended frame size. A host-side ifconfig value cannot make the remote network carry a frame it rejects.

Measure both directions and multiple protocols. ICMP filtering can make a path-MTU test inconclusive; use a supported diagnostic method and correlate packet captures at the PPP and Ethernet interfaces. Be aware that hardware offload may make local captures differ from wire-level frames. Record the actual failure size and point of loss rather than repeatedly reducing the MTU until a symptom disappears.

Reconnects, route ownership, and DNS updates

ddial performs a dial action whenever the line is down, while set redial controls the delay and attempt limit for failed connection attempts. These retry settings do not guarantee that every application recovers after a session change. The negotiated peer or address may change; routes and nameservers can be updated; existing TCP sessions generally cannot survive a new transport path. Design applications and monitoring to tolerate a reconnect rather than mistaking it for a transparent link-layer failover.

Before restarting ppp, capture ifconfig, routes, resolver state, and PPP logs. A restart can remove the tunnel and default route, interrupt remote access, and trigger new authentication. Verify that a second management route or console exists if the PPP link is the only way to administer the host. For dual-WAN routing, define which interface owns the default route and how failover policy handles return traffic; do not expect two independent default routes to behave as a health-checked router automatically.

DNS negotiation through enable dns can write nameserver information into /etc/resolv.conf according to ppp configuration. Do not enable it blindly if a local resolver expects 127.0.0.1 or if a VPN supplies split DNS. Keep resolver ownership explicit, test queries after link-up and link-down, and check whether the chosen generator restores the previous values on disconnect.

Diagnose frequent PPPoE failures

Ethernet is up, but no PPPoE session appears. Reconfirm modem bridge mode, physical interface, service tag, VLAN path, provider availability, and any switch filtering. Capture a bounded trace at the Ethernet interface if authorized. Do not troubleshoot DNS before the PPP session exists.

Discovery succeeds but authentication fails. Confirm the account identifier, authentication method, credential handling, and whether the provider binds service to a line or equipment ID. Preserve the exact failure message but redact secrets. Avoid repeatedly trying credentials if the provider locks accounts after failures.

LCP is up but no usable IP connectivity exists. Inspect IPCP/IPv6CP logs, tun address state, default route, peer route, and provider policy. Confirm the configured set ifaddr values are negotiation hints rather than assumed assigned addresses. Coordinate a static configuration with the provider if the account requires it.

The session connects and immediately drops. Compare LCP echo/timeouts, carrier transitions, provider logs, idle policy, and link errors. Check whether a local firewall or competing PPP process terminates traffic. Change one timer at a time and retain the original profile.

Only large transfers stall. Check MTU/MRU agreement, path-MTU discovery, encapsulation overhead, and firewall handling. Capture at both the physical and tunnel interfaces. Do not change credentials, service tags, and MTU together.

Prove the connection is production-ready

Acceptance requires more than a tun0 device. Verify a complete discovery/authentication/network-layer negotiation, correct local and peer addresses, intended route ownership, DNS behavior, and bidirectional application traffic. Exercise an orderly service stop/start, a provider-side disconnect if available, and a reboot in a controlled window. Confirm that reconnect completes within the service’s recovery objective and that monitoring sees both outage and restoration.

Document the NIC and switch/modem topology, exact provider profile name, whether a service tag is used, credential ownership, address type, route policy, MTU/MRU, resolver owner, NAT decision, logging path, and recovery contact. Monitor tunnel state, session duration, reconnect count, authentication failures, route presence, and application reachability. Do not alert only on Ethernet carrier: the physical link can remain up while PPP negotiation or provider routing is broken.

PPPoE is dependable when its state transitions are observable and its external assumptions are written down. Keep authentication, link state, route installation, DNS, and application health as distinct checks. That separation turns a vague “internet down” incident into a stage-specific diagnosis and keeps reconnect behavior from silently masking a provider or configuration failure.

Related:

Sources: