Linux PPPoE: A Credential-Safe NetworkManager Troubleshooting Guide

PPPoE carries a PPP session over Ethernet; it is not the same thing as ADSL, fiber, or broadband itself. In most home networks today, the ONT or router initiates PPPoE. Linux should establish a direct PPPoE session only when the provider has put the equipment in bridge mode and explicitly requires the host to connect. For terminology, see this site's guide to broadband, ADSL, and PPPoE.

This guide prioritizes current NetworkManager and distribution-supported tools. Do not install an unknown old RPM, run NetworkManager, pppoeconf, a hand-written pppd service, and router dialing at the same time, or blindly overwrite resolver or firewall configuration.

Table of Contents

First determine where PPPoE terminates

Current topology	What Linux usually sees	Correct action
The ONT or router handles PPPoE	Ethernet or Wi-Fi receives a private address and default gateway through DHCP	Do not add PPPoE on Linux; diagnose WAN status in the authorized router interface
The ONT is bridged and Linux is directly connected	The physical Ethernet link has no ordinary internet address and the provider requires this host to dial	Only then consider creating PPPoE on that interface
The bridged service also uses a VLAN	The provider requires a specific VLAN ID, with PPPoE on the VLAN interface	Create the VLAN from provider documentation first, then bind PPPoE to it; never guess the ID
Enterprise or apartment shared access	A gateway, authentication appliance, or concurrency restriction may already exist	Ask the network administrator first; do not scan access concentrators or displace another session

Check the ONT or router WAN status first. If it already reports a connected PPPoE session, dialing again from Linux creates a duplicate or concurrent session and may evict the original one. Changing an ONT to bridge mode can also disrupt IPTV, voice, VLANs, and remote maintenance; do not change it without approval from the provider or device owner.

Obtain exact provider parameters

Record the following before changing anything, and keep it only in an approved private location:

Exact account format, official password-reset route, and concurrent-session limit.
Whether PPPoE terminates on the router or host, and the required physical port.
Whether a VLAN ID, PPPoE service name, or named access concentrator is required.
IPv4 addressing, default route, DNS, and whether native IPv6, prefix delegation, or static parameters are provided.
Provider-supported MTU and MRU; do not force 1492 merely because it is common online.
Whether the account is bound to a device, MAC, line, or previous session, and how long stale-session release takes.

Do not post the real username, password, contract number, MAC, public address, or complete logs to forums, ticket screenshots, or AI chats. The example identity in this article uses the RFC 2606 reserved .invalid domain and does not represent a real subscriber.

Preserve remote access and record a baseline

Stop if the SSH, VPN, jump host, or remote desktop session currently uses the interface you plan to change. Have a local console or independent management path, a backup of the existing configuration, a named rollback owner, and a maintenance window. Do not assume that the connection will automatically return.

These commands read ordinary network state, but their output can still contain hostnames, interfaces, addresses, routes, and connection names. Redact each field before sharing:

nmcli general status
nmcli device status
nmcli connection show --active
ip -brief link
ip -brief address
ip route show default
ip -6 route show default

Identify the actual Ethernet interface rather than copying the historical eth0. Also determine which system owns it: NetworkManager, systemd-networkd, Netplan, ifupdown, or another platform service. One interface should have one configuration owner.

Diagnose before changing

Symptom	Check first	Do not do immediately
No access concentrator or discovery timeout	Termination point, cable, ONT bridge mode, parent interface, VLAN, service name, link state	Re-enter passwords repeatedly, disable the firewall, or swap random packages
Authentication failure	Account format and state, official reset, line or device binding, stale session	Put the password in a command or publish a complete log
Session connects and immediately drops	Concurrent or double dialing, line events, provider session release, PPP negotiation	Start multiple PPP clients at once
Address exists but no default route	PPP default-route setting, route priority, competing WAN profiles	Delete every route or overwrite all network configuration
IP works but names fail	DNS learned by NetworkManager, system resolver, split DNS	Download an old DNS list or overwrite `/etc/resolv.conf`
Small requests work but large transfers stall	Effective MTU, Path MTU Discovery, ICMP filtering, provider support	Change MSS at random or increase MTU blindly
IPv4 works but IPv6 fails	Whether the provider offers IPv6, IPV6CP, address, prefix, and default route	Disable IPv6 globally to conceal the fault

If authentication repeatedly fails, stop retries and contact the provider to avoid account lockout. Failure to discover a PPPoE access concentrator is usually not a password problem.

Inspect an existing NetworkManager profile

Do not use options that display secrets, and do not paste a complete profile into a public venue. This example selects only non-password fields; isp-pppoe is an example connection name:

nmcli -f connection.id,connection.type,connection.interface-name,connection.autoconnect,pppoe.service,ppp.mtu,ipv4.method,ipv6.method connection show isp-pppoe

Check the parent interface, service name, autoconnect setting, MTU, and IPv4 and IPv6 methods. The username is also a personal or contract identifier and should be redacted from public records. Do not read or export pppoe.password, and do not copy NetworkManager system connection files.

A bounded local configuration path

Prefer the desktop network settings or a distribution-provided NetworkManager frontend so secrets go to a desktop secret agent or approved secret store. The command-line path below applies only when the provider confirms host-based dialing, no VLAN, no service name, a parent interface of enp1s0, and NetworkManager ownership of that interface.

Create a non-autoconnecting example profile first. The reserved fake identity makes accidental execution fail authentication safely; never append the real password to a command:

nmcli connection add type pppoe ifname enp1s0 con-name isp-pppoe pppoe.username subscriber@example.invalid pppoe.password-flags 2 connection.autoconnect no
nmcli connection edit isp-pppoe
nmcli --ask connection up isp-pppoe

In the interactive editor, replace the fake username with the exact value supplied by the provider; do not record or share the terminal. pppoe.password-flags 2 means the password is not saved, and nmcli --ask prompts when it is required. If unattended reconnection is required, use the distribution-supported secret agent or organizational secret-management route, not shell history, a script, an environment variable, or a readable configuration file.

If a VLAN or service name is required, stop rather than inventing a value; follow current provider and distribution documentation for the exact parent interface or property. If configuration authorization fails, use the distribution's PolicyKit or administrator process instead of loosening connection-file permissions.

Rollback protection for remote changes

Only newer NetworkManager releases provide nmcli device checkpoint. Check local help first; if checkpoint is absent, do not attempt the change remotely. If it is present, the time-limited command below restores the checkpoint when confirmation is not received, but it does not replace an independent management path or local operator:

nmcli device help
nmcli device checkpoint --timeout 120 enp1s0 -- nmcli --ask connection up isp-pppoe

If the current uplink is dropped from the same remote session, the confirmation prompt may never reach you. The safest approach remains a local console or a management path that does not traverse this interface.

Verify layer by layer

Do not stop at a “connected” label. Identify the actual PPP interface, then verify addressing, routes, DNS, MTU, and IPv6 by layer:

nmcli connection show --active
ip -brief address
ip route show default
ip -6 route show default
nmcli -f IP4.DNS,IP6.DNS device show ppp0
ip link show dev ppp0
getent ahosts example.com

ppp0 is only a common example and must be replaced with the real interface. Acceptance should include: exactly one intended PPPoE session; the correct connection supplies the IPv4 address and default route; the system resolver works; IPv6 addressing and the default route match the provider commitment; the firewall remains enabled; restart or reconnection behavior matches policy; and the old uplink can be restored after disconnecting.

Test public reachability, Path MTU, or latency only against a target you or the provider explicitly authorizes, and record the target, time, and packet size. Resolving example.com tests name service only; it does not prove that every internet path works.

MTU and large-packet failures

RFC 2516 describes the traditional 1492-byte PPPoE limit over 1500-byte Ethernet. RFC 4638 describes negotiation above that limit when the whole path supports it. Neither means “always enter 1492” or “larger is always better.”

Record the effective MTU reported by ip link, then confirm end-to-end support across the provider access, VLAN, ONT, switches, and peer. Only when large packets fail while small ones succeed should you make one recorded MTU change in an isolated test, restoring the original value if it fails. Do not use a global MSS rewrite to conceal an unknown path fault.

DNS, IPv6, and the firewall

DNS should be managed through NetworkManager and the system resolver in the distribution-supported way. If the provider supplies bad DNS, an approved server can be set on the single connection, but first record the original value, split-DNS behavior, and privacy requirements. Do not download old DNS lists or blindly rewrite /etc/resolv.conf.

IPv6 availability depends on the provider's PPP and prefix design. Check address assignment, default route, DNS, and downstream prefix delegation separately; “the provider offers no IPv6” and “Linux is misconfigured” are different conclusions. Do not globally disable IPv6 as a generic fix.

A PPPoE interface usually faces the provider network directly. Retain the host firewall and a default-deny inbound policy. If the host is a router, forwarding, NAT, IPv6 routing, and downstream filtering require a separate security review. A historical wizard's “NONE” choice is not a reason to disable the firewall today.

Log and credential safety

Start with the distribution's default log level; do not immediately enable TRACE logging or a packet capture that may expose authentication material. This read may contain a username, addresses, access concentrator, and connection identifiers. View it only in a controlled terminal, then minimize and redact before sharing:

journalctl -b -u NetworkManager --no-pager -n 200

Do not screenshot password prompts, use positional password arguments, or place a secret in shell history, environment variables, clipboard managers, debug bundles, or tickets. If compromise is suspected, reset the password through the provider's official route and clean copies from authorized logs and secret stores.

Distribution differences

NetworkManager's nmcli manual defines interactive prompting and checkpoint behavior, while the settings manual defines pppoe.parent, username, password-flags, and the usually empty service. Distributions may package older NetworkManager releases, so check local nmcli --version and help first.

The Debian Reference networking chapter warns that NetworkManager and traditional ifupdown configuration can conflict. Red Hat Enterprise Linux 9 documentation recommends managing keyfiles through supported interfaces such as nmcli, not by hand. If the system does not use NetworkManager, use one currently supported tool and guide for that distribution; do not mix Red Hat, Ubuntu, BackTrack, Slax, and old CentOS procedures.

Rollback and stop conditions

If the new profile does not work, perform this minimum rollback from the local console. Do not run it remotely when that session depends on PPPoE:

nmcli connection modify isp-pppoe connection.autoconnect no
nmcli connection down isp-pppoe

Then restore and verify the previously recorded uplink. Do not rush to delete the new profile, because it may be needed for comparison; remove it only later through the authorized configuration-management process.

Stop immediately if ownership or management authority is unclear; the current remote session has no backup path; the ONT or router is already dialing; exact provider parameters are missing; the change would affect voice, IPTV, or someone else's network; logs may have exposed a secret; line equipment is hot or damaged; or progress would require disabling the firewall, downloading an unknown binary, overwriting global network configuration, or repeatedly retrying a password.

Official references

Archived 2011 source

The inert plain-text fence below preserves the complete visible source_export body with exactly four disclosed safety substitutions: the single occurrence of http://earn.yesmall.biz/?p=724 is replaced by [historical internal HTTP link redacted]; the dead, insecure DNS download URL occurs twice and both instances are replaced by [dead HTTP DNS download redacted]; and one real-looking historical subscriber username is replaced by [historical subscriber username redacted]. The source contains no actual password value, so its password prompts remain. There was no trailing whitespace to normalize. This archive is not current guidance: do not follow its old RPM, answer-everything-Yes, firewall-disablement, BackTrack, or direct configuration-editing instructions.

点击阅读：[宽带、窄带，ADSL、pppoe，虚拟拨号等名词解释]([historical internal HTTP link redacted])

当初在虚拟机中第一次安装好了红帽，在百度上Google了N次，逛了无数的论坛、博客，看了无数的帖子、文章，在网上找了各种方法，怎么也找不到“宽带”连上网的方法。

后来用Ubuntu也是这样，ubuntu自带的客户端根本连不上网，想找个连上网的办法吧，结果我见到的回答全是牛头不对马嘴，真是让人气馁。

虽然Linux各种发行版的命令大体一样，但有一些还是不同的。

Table of Contents

Toggle

- [Red Hat Linux](https://blog.lazying.art/en/html/computer_internet/717/%e5%90%84%e7%a7%8dlinux%e5%8f%91%e8%a1%8c%e7%89%88%e4%b8%8b%e7%9a%84pppoe%e6%8b%a8%e5%8f%b7%e5%91%bd%e4%bb%a4%e6%94%b6%e9%9b%86%e6%95%b4%e7%90%86.html/#Red_Hat_Linux)
- [Ubuntu](https://blog.lazying.art/en/html/computer_internet/717/%e5%90%84%e7%a7%8dlinux%e5%8f%91%e8%a1%8c%e7%89%88%e4%b8%8b%e7%9a%84pppoe%e6%8b%a8%e5%8f%b7%e5%91%bd%e4%bb%a4%e6%94%b6%e9%9b%86%e6%95%b4%e7%90%86.html/#Ubuntu)
- [CentOS](https://blog.lazying.art/en/html/computer_internet/717/%e5%90%84%e7%a7%8dlinux%e5%8f%91%e8%a1%8c%e7%89%88%e4%b8%8b%e7%9a%84pppoe%e6%8b%a8%e5%8f%b7%e5%91%bd%e4%bb%a4%e6%94%b6%e9%9b%86%e6%95%b4%e7%90%86.html/#CentOS)
- [BackTrack Linux](https://blog.lazying.art/en/html/computer_internet/717/%e5%90%84%e7%a7%8dlinux%e5%8f%91%e8%a1%8c%e7%89%88%e4%b8%8b%e7%9a%84pppoe%e6%8b%a8%e5%8f%b7%e5%91%bd%e4%bb%a4%e6%94%b6%e9%9b%86%e6%95%b4%e7%90%86.html/#BackTrack_Linux)
- [Slax](https://blog.lazying.art/en/html/computer_internet/717/%e5%90%84%e7%a7%8dlinux%e5%8f%91%e8%a1%8c%e7%89%88%e4%b8%8b%e7%9a%84pppoe%e6%8b%a8%e5%8f%b7%e5%91%bd%e4%bb%a4%e6%94%b6%e9%9b%86%e6%95%b4%e7%90%86.html/#Slax)

## Red Hat Linux

Red Hat Linux下面使用的是ADSL：调制解调器命令
 作用：ADSL调制解调器命令用来配置宽带调制解调器工作。
 说明：ADSL命令包括一组命令。首先检查是否安装了PPPOE软件，并且版本号要高于3.5-1。如果版本低于这个版本号，先升级软件版本（最新版本rp-ppoe-3.5-3.i386.rpm）。升级命令如下：
 [root@sample ~]# rpm Uvh rp-ppp-3.5-3.i386.rpm

**友情提示：我认为升级并不是必要的，如果你确定要升级，先在其它电脑上下载最新PPPOE软件，放在“/Home/你的用户名/”下面（因为终端默认路径就是这个文件夹），再执行上面的命令即可**（注意命令的大小写、文件名为你的下载的文件的文件名）

系统产生如下四个命令。

- adsl-setup：配置DNS、用户账号、密码、其他选项。
- adsl-start：使用ADSL连接互联网命令。
- adsl-stop：断开ADSL和互联网连接命令。
- adsl-status：检测ADSL连接状态命令。

[root@sample ~]# adsl-setup ← 建立ADSL连接

Welcome to the ADSL client setup. First, I will run some checks on
 your system to make sure the PPPoE client is installed properly…

LOGIN NAME

Enter your Login Name (default root): ← 填入ADSL连接的用户名

INTERFACE

Enter the Ethernet interface connected to the ADSL modem
 For Solaris, this is likely to be something like /dev/hme0.
 For Linux, it will be ethX, where ‘X’ is a number.
(default eth0): ← 指定网络接入设备，一块网卡的情况下，一般为默认eth0

Do you want the link to come up on demand, or stay up continuously?
 If you want it to come up on demand, enter the idle time in seconds
 after which the link should be dropped. If you want the link to
 stay up permanently, enter ‘no’ (two letters, lower-case.)
 NOTE: Demand-activated links do not interact well with dynamic IP
 addresses. You may have some problems with demand-activated links.
Enter the demand value (default no): ← 直接按回车，接受默认设置

DNS

Please enter the IP address of your ISP’s primary DNS server.
 If your ISP claims that ‘the server will provide dynamic DNS addresses’,
 enter ‘server’ (all lower-case) here.
 If you just press enter, I will assume you know what you are
 doing and not modify your DNS setup.
Enter the DNS information here: ← 如果知道DNS服务器的信息在此填入。不知道的情况按回车跳过（《全国DNS服务器IP地址》下载地址：[[dead HTTP DNS download redacted]]([dead HTTP DNS download redacted])）

PASSWORD

Please enter your Password: ← 输入ADSL的连接密码
 Please re-enter your Password: ← 再次确认输入ADSL的连接密码

USERCTRL

Please enter ‘yes’ (two letters, lower-case.) if you want to allow
normal user to start or stop DSL connection (default yes): no ← 填入no，不允许一般用户控制PPPoE的连接

FIREWALLING

Please choose the firewall rules to use. Note that these rules are
 very basic. You are strongly encouraged to use a more sophisticated
 firewall setup; however, these will provide basic security. If you
 are running any servers on your machine, you must choose ‘NONE’ and
 set up firewalling yourself. Otherwise, the firewall rules will deny
 access to all standard servers like Web, e-mail, ftp, etc. If you
 are using SSH, the rules will block outgoing SSH connections which
 allocate a privileged source port.

The firewall choices are:
 0 – NONE: This script will not set any firewall rules. You are responsible
 for ensuring the security of your machine. You are STRONGLY
 recommended to use some kind of firewall rules.
 1 – STANDALONE: Appropriate for a basic stand-alone web-surfing workstation
 2 – MASQUERADE: Appropriate for a machine acting as an Internet gateway
 for a LAN
Choose a type of firewall (0-2): 0 ← 输入0，不在这里使用防火墙

Start this connection at boot time

Do you want to start this connection at boot time?
Please enter no or yes (default no): yes ← 填入yes，在系统启动时自动连接ADSL

** Summary of what you entered **

Ethernet Interface: eth0
 User name: [historical subscriber username redacted]
 Activate-on-demand: No
 DNS: Do not adjust
 Firewalling: NONE
 User Control: no
Accept these settings and adjust configuration files (y/n)? y ← 配置信息确认无误后，键入y同意设置
 Adjusting /etc/sysconfig/network-scripts/ifcfg-ppp0
 Adjusting /etc/ppp/chap-secrets and /etc/ppp/pap-secrets
 (But first backing it up to /etc/ppp/chap-secrets.bak)
 (But first backing it up to /etc/ppp/pap-secrets.bak)

…………

…………

Congratulations, it should be all set up!

Type ‘/sbin/ifup ppp0’ to bring up your xDSL link and ‘/sbin/ifdown ppp0’
 to bring it down.
 Type ‘/sbin/adsl-status /etc/sysconfig/network-scripts/ifcfg-ppp0’
 to see the link status.
[root@sample ~]# adsl-start ← 启动ADSL连接

[root@sample ~]# ← 稍等片刻后若启动成功后出现提示符（无任何提示即意味着连接成功）

## Ubuntu

1、打开应用程序菜单，依次选择“附件”->“终端”。
 2、在弹出终端窗口后
[root@sample ~]# sudo pppoeconf <- 输入完成后回车
 3、然后会提示用户输入当前Ubuntu管理员用户的密码，输入完成后回车。询问网络设备，一般选择“是”，进行检测，然后选择“是”。
 4、之后会提示输入用户的ADSL用户名（也就是账号）和密码，在输入账号时把原来的user删掉，其他的除密码之外的问题全部回答“是”（Yes）就可以了。
 5、最后会提示用户是否开机自动拨号，选择“是”（Y）的话，默认开机会没有任何提示的情况下拨号，直接可以上网。如果选择“否”（N）的话，需要拨号时手工进入终端输入
[root@sample ~]# sudo pon dsl-provider <- 输入完成后回车
 6、经常使用的命令。
 pon：启用adsl链接。
 poff：结束adsl连接。
 plog：查看adsl的提示信息，作为调试用。
 ifconfig ppp0：查看是否有ppp0接口。
 route -n：查看默认网关是否正确。
 nslookup：查看DNS是否能够正确解析。
 这些命令可以帮助大家解决ADSL上网遇到的问题，也可以用来调试ADSL。

## CentOS

同Red Hat Linux

## BackTrack Linux

同Red Hat Linux

## Slax

同Red Hat Linux