diff options
Diffstat (limited to 'docs/interfaces/pppoe.rst')
| -rw-r--r-- | docs/interfaces/pppoe.rst | 161 |
1 files changed, 122 insertions, 39 deletions
diff --git a/docs/interfaces/pppoe.rst b/docs/interfaces/pppoe.rst index 42d7c3b4..576513a1 100644 --- a/docs/interfaces/pppoe.rst +++ b/docs/interfaces/pppoe.rst @@ -1,79 +1,162 @@ -.. _pppoe: - +.. _pppoe-interface: PPPoE ===== -There are two main ways to setup VyOS to connect over a PPPoE internet connection. This is due to most ISPs (Internet Service Providers) providing a DSL modem that is also a wireless router. - -**First Method:** (Common for Homes) - -In this method, the DSL Modem/Router connects to the ISP for you with your credentials preprogrammed into the device. This gives you an :rfc:`1918` address, such as ``192.168.1.0/24`` by default. +:abbr:`PPPoE (Point-to-Point Protocol over Ethernet)` is a network protocol +for encapsulating PPP frames inside Ethernet frames. It appeared in 1999, +in the context of the boom of DSL as the solution for tunneling packets +over the DSL connection to the :abbr:`ISPs (Internet Service Providers)` +IP network, and from there to the rest of the Internet. A 2005 networking +book noted that "Most DSL providers use PPPoE, which provides authentication, +encryption, and compression." Typical use of PPPoE involves leveraging the +PPP facilities for authenticating the user with a username and password, +predominately via the PAP protocol and less often via CHAP. + +Operating Modes +--------------- + +VyOS supports setting up PPPoe in two different ways to a PPPoE internet +connection. This is due to most ISPs provide a modem that is also a wireless +router. + +Home Users +********** + +In this method, the DSL Modem/Router connects to the ISP for you with your +credentials preprogrammed into the device. This gives you an :rfc:`1918` +address, such as ``192.168.1.0/24`` by default. + +For a simple home network using just the ISP's equipment, this is usually +desirable. But if you want to run VyOS as your firewall and router, this +will result in having a double NAT and firewall setup. This results in a +few extra layers of complexity, particularly if you use some NAT or +tunnel features. + +Business Users +************** + +In order to have full control and make use of multiple static public IP +addresses, your VyOS will have to initiate the PPPoE connection and control +it. In order for this method to work, you will have to figure out how to make +your DSL Modem/Router switch into a Bridged Mode so it only acts as a DSL +Transceiver device to connect between the Ethernet link of your VyOS and the +phone cable. Once your DSL Transceiver is in Bridge Mode, you should get no +IP address from it. Please make sure you connect to the Ethernet Port 1 if +your DSL Transeiver has a switch, as some of them only work this way. + +Once you have an Ethernet device connected, i.e. `eth0`, then you can +configure it to open the PPPoE session for you and your DSL Transceiver +(Modem/Router) just acts to translate your messages in a way that +vDSL/aDSL understands. + +Configuration Example +~~~~~~~~~~~~~~~~~~~~~ + +Requirements: + +* Your ISPs modem is connected to port ``eth0`` of your VyOS box. +* No VLAN tagging required by your ISP. +* You need your PPPoE credentials from your DSL ISP in order to configure + this. The usual username is in the form of name@host.net but may vary + depending on ISP. +* The largest MTU size you can use with DSL is 1492 due to PPPoE overhead. + If you are switching from a DHCP based ISP like cable then be aware that + things like VPN links may need to have their MTU sizes adjusted to work + within this limit. +* With the ``default-route`` option set to ``auto``, VyOS will only add the + default gateway you receive from your DSL ISP to the routing table if you + have no other WAN connections. If you wish to use a dual WAN connection, + change the ``default-route`` option to ``force``. +* With the ``name-server`` option set to ``none``, VyOS will ignore the + nameservers your ISP sens you and thus you can fully rely on the ones you + have configured statically. -For a simple home network using just the ISP's equipment, this is usually desirable. But if you want to run VyOS as your firewall and router, this will result in having a double NAT and firewall setup. This results in a few extra layers of complexity, particularly if you use some NAT or tunnel features. +.. code-block:: sh -**Second Method:** (Common for Businesses) + set interfaces ethernet eth0 description "DSL Modem" + set interfaces ethernet eth0 duplex auto + set interfaces ethernet eth0 smp_affinity auto + set interfaces ethernet eth0 speed auto + set interfaces ethernet eth0 pppoe 0 default-route 'auto' + set interfaces ethernet eth0 pppoe 0 mtu 1492 + set interfaces ethernet eth0 pppoe 0 name-server 'auto' + set interfaces ethernet eth0 pppoe 0 user-id 'userid' + set interfaces ethernet eth0 pppoe 0 password 'secret' -In order to have full control and make use of multiple static public IP addresses, your VyOS will have to initiate the PPPoE connection and control it. -In order for this method to work, you will have to figure out how to make your DSL Modem/Router switch into a Bridged Mode so it only acts as a DSL Transceiver device to connect between the Ethernet link of your VyOS and the phone cable. -Once your DSL Transceiver is in Bridge Mode, you should get no IP address from it. -Please make sure you connect to the Ethernet Port 1 if your DSL Transeiver has a switch, as some of them only work this way. -Once you have an Ethernet device connected, i.e. eth0, then you can configure it to open the PPPoE session for you and your DSL Transceiver (Modem/Router) just acts to translate your messages in a way that vDSL/aDSL understands. -**Here is an example configuration:** +You should add a firewall to your configuration above as well by +assigning it to the pppoe0 itself as shown here: .. code-block:: sh - set interface ethernet eth0 description "DSL Modem" - set interface ethernet eth0 duplex auto - set interface ethernet eth0 smp_affinity auto - set interface ethernet eth0 speed auto - set interface ethernet eth0 pppoe 0 default-route auto - set interface ethernet eth0 pppoe 0 mtu 1492 - set interface ethernet eth0 pppoe 0 name-server auto - set interface ethernet eth0 pppoe 0 user-id <PPPoE Username> - set interface ethernet eth0 pppoe 0 password <PPPoE Password> + set interfaces ethernet eth0 pppoe 0 firewall in name NET-IN + set interfaces ethernet eth0 pppoe 0 firewall local name NET-LOCAL + set interfaces ethernet eth0 pppoe 0 firewall out name NET-OUT +VLAN Example +++++++++++++ -* You should add a firewall to your configuration above as well by assigning it to the pppoe0 itself as shown here: +Some recent ISPs require you to build the PPPoe connection through a VLAN +interface. One of those ISPs is e.g. Deutsche Telekom in Germany. VyOS +can easily create a PPPoe session through an encapsulated VLAN interface. +The following configuration will run your PPPoE connection through VLAN7 +which is the default VLAN for Deutsche Telekom: .. code-block:: sh - set interface ethernet eth0 pppoe 0 firewall in name NET-IN - set interface ethernet eth0 pppoe 0 firewall local name NET-LOCAL - set interface ethernet eth0 pppoe 0 firewall out name NET-OUT + set interfaces ethernet eth0 description "DSL Modem" + set interfaces ethernet eth0 duplex auto + set interfaces ethernet eth0 smp_affinity auto + set interfaces ethernet eth0 speed auto + set interfaces ethernet eth0 vif 7 pppoe 0 default-route 'auto' + set interfaces ethernet eth0 vif 7 pppoe 0 mtu '1492' + set interfaces ethernet eth0 vif 7 pppoe 0 name-server 'auto' + set interfaces ethernet eth0 vif 7 pppoe 0 user-id 'userid#0001@t-online.de' + set interfaces ethernet eth0 vif 7 pppoe 0 password 'secret' -* You need your PPPoE credentials from your DSL ISP in order to configure this. The usual username is in the form of name@host.net but may vary depending on ISP. -* The largest MTU size you can use with DSL is 1492 due to PPPoE overhead. If you are switching from a DHCP based ISP like cable then be aware that things like VPN links may need to have their MTU sizes adjusted to work within this limit. -* With the ``default-route`` option set to ``auto``, VyOS will only add the Default Gateway you receive from your DSL ISP to the routing table if you have no other WAN connections. If you wish to use a Dual WAN connection, change the ``default-route`` option to ``force``. +Troubleshooting +--------------- -Handling and troubleshooting ----------------------------- +Connect/Disconnect +****************** -You can test connecting and disconnecting with the below commands: +You can test connecting and disconnecting with the below commands issued +on the operational level of your VyOS isntallation: .. code-block:: sh disconnect interface 0 connect interface 0 +Logs +**** -You can check the PPPoE connection logs with the following: - -This command shows the current statistics, status and some of the settings (i.e. MTU) for the current connection on pppoe0. +You can check the PPPoE connection logs with the following command which +shows the current statistics, status and some of the settings (i.e. MTU) +for the current connection on pppoe0. .. code-block:: sh show interfaces pppoe 0 -This command shows the entire log for the PPPoE connection starting with the oldest data. Scroll down with the <space> key to reach the end where the current data is. +Full Log +~~~~~~~~ + +This command shows the entire log for the PPPoE connection starting with the +oldest data. Scroll down with the <space> key to reach the end where the +current data is. .. code-block:: sh show interfaces pppoe 0 log +Recent Log +~~~~~~~~~~ -This command shows the same log as without the 'tail' option but only starts with the last few lines and continues to show added lines until you exit with ``Ctrl + x`` +This command shows the same log as without the 'tail' option but only starts +with the last few lines and continues to show added lines until you exit with +``Ctrl + x`` .. code-block:: sh |