upstream/opnsense-docs
1
0
Fork 0
mirror of https://github.com/opnsense/docs.git synced 2026-05-28 04:02:12 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

devices: Add Point-to-point to general overview and add how-to for ISP setup with PPPoE (#674)

Browse source 
* devices: Add Point-to-point to general overview

* devices: Add Point-to-point how-to

* Update source/manual/other-interfaces.rst

Co-authored-by: Franco Fichtner <franco@opnsense.org>

* devices: Add Point-to-point Setup Guide

* devices: Add Point-to-point log file location

---------

Co-authored-by: Franco Fichtner <franco@opnsense.org>
This commit is contained in:
Monviech 2025-03-07 10:15:46 +01:00 committed by GitHub
parent 871b563b57
commit b3abc48b9a
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 255 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

145
source/manual/how-tos/pppoe_isp_setup.rst Normal file
View file

@ -0,0 +1,145 @@
============================
PPPoE ISP Setup
============================
.. contents:: Index
----------------------------
Summary
----------------------------
This guide covers the configuration of a PPPoE setup that subscribes the OPNsense to a Provider Edge Router (PE).
Most providers require a VLAN tag in modern setups, this guide will focus on that. If your setup does not require,
set the PPPoE device directly on the parent interface.
See the section on `Point-to-Point </manual/other-interfaces.html#point-to-point>`_ for more details.
----------------------------
Setup Overview
----------------------------
Your ISP provides you the following information to connect via PPPoE:
- Username: ``123456789001@example.com``
- Password: ``HelloWorld``
- VLAN Tag: ``7``
We assume the default WAN interface is ``igc1``.
----------------------------
Configuration
----------------------------
1. Parent Interface
----------------------------
The parent interface for the PPPoE connection is usually the WAN interface. This interface is assigned per default.
When using a VLAN, remove the IP configuration from it.
- Go to :menuselection:`Interfaces --> WAN` and set:
================================== =======================================================================================================
Option Value
================================== =======================================================================================================
**IPv4 Configuration Type** ``None``
**IPv6 Configuration Type** ``None``
================================== =======================================================================================================
- Press **Save** and **Apply**
.. Tip:: If you do not plan to use this interface at all, you can also unassign it. Only the VLAN interface must be assigned for PPPoE to work.
2. VLAN Interface
----------------------------
Create a VLAN interface on the WAN interface.
- Go to :menuselection:`Interfaces --> Devices --> VLAN` and create a new VLAN interface with the following settings:
================================== =======================================================================================================
Option Value
================================== =======================================================================================================
**Device** ``vlan0.1.7``
**Parent interface** ``igc1``
**VLAN tag** ``7``
**VLAN priority** Leave default
**Description** ``vlan0.1.7``
================================== =======================================================================================================
- Press **Save** and **Apply**
.. Note:: `Device` can optionally be left empty to auto assign the vlan device name.
- Next, go to :menuselection:`Interfaces --> Assignments` and assign the VLAN interface you just created.
================================== =======================================================================================================
Option Value
================================== =======================================================================================================
**Device** ``vlan0.1.7``
**Description** ``igc1_vlan7_PPPoE``
================================== =======================================================================================================
- Press **Add**
3. PPPoE Interface
----------------------------
Now, we create the Point-to-Point device that we attach to the prior created VLAN.
Go to :menuselection:`Interfaces --> Devices --> PPPoE` and create a new PPPoE interface with the following settings:
================================== =======================================================================================================
Option Value
================================== =======================================================================================================
**Link Type** ``PPPoE``
**Link interface(s)** ``vlan0.1.7``
**Username** ``123456789001@example.com``
**Password** ``HelloWorld``
================================== =======================================================================================================
- Press **Save**
Go to :menuselection:`Interfaces --> igc1_vlan7_PPPoE` and validate the settings:
================================== =======================================================================================================
Option Value
================================== =======================================================================================================
**IPv4 Configuration Type** ``PPPoE``
================================== =======================================================================================================
- Press **Save** and **Apply**
Now the PPPoE connection should be up and running when connecting ``igc1`` to the ISP provided Modem or ONT.
4. Logfiles
-------------------------------
The ``ppp`` log files can be found in :menuselection:`System --> Log Files --> General`.
.. Tip:: The Link Control Procol will reveal most Link Layer and Authorization issues. Filtering for these messages is the best way to troubleshoot Point-to-Point connections.
A successful LCP (Link Control Protocol) sequence should look like this:
::
LCP: Open event
LCP: state change Initial --> Starting
LCP: LayerStart
LCP: Up event
LCP: state change Starting --> Req-Sent
LCP: SendConfigReq #1
LCP: rec'd Configure Request #105 (Req-Sent)
LCP: SendConfigAck #105
LCP: state change Req-Sent --> Ack-Sent
LCP: rec'd Configure Ack #1 (Ack-Sent)
LCP: state change Ack-Sent --> Opened
LCP: auth: peer wants PAP, I want nothing
LCP: LayerUp
LCP: authorization successful

110
source/manual/other-interfaces.rst
View file

@ -265,3 +265,113 @@ source in the encapsulating IPv4/IPv6 header.
Read `VXLAN Bridge </manual/how-tos/vxlan_bridge.html>`_ for an example configuration with a common setup.
----------------
Point-to-Point
----------------
Point-to-Point (PP) interfaces provide direct connectivity between two endpoints without any intermediary devices. These interfaces are commonly used for WAN connections,
tunneling, or direct link setups where `broadcast` and `multiple access` are not needed.
The following `Link Types` are available for these interfaces:
.. tabs::
.. tab:: PPP (Point-to-Point Protocol)
A widely used protocol for establishing direct connections over serial links, often utilized for
dial-up and DSL connections. Supports authentication (PAP/CHAP), compression, and error detection.
========================================= ====================================================================================
**Option** **Description**
========================================= ====================================================================================
**Link interfaces** Select one interface for normal PPP and least two interfaces for Multilink (MLPPP) connections.
**Description** You may enter a description here for your reference. Description will appear in the "Interfaces Assign" select lists
**Service Provider** Select the country, Provider and Plan for the PPP connection.
**Username** Enter your username for CHAP authentication.
**Password** Enter your password for CHAP authentication.
**Phone Number** Typically ``*99#`` for GSM networks and ``#777`` for CDMA networks
**Access Point Name (APN)** Enter the APN for your service provider. E.g., ``internet.t-d1.de`` for T-Mobile.
========================================= ====================================================================================
========================================= ====================================================================================
**Advanced Option** **Description**
========================================= ====================================================================================
**APN number (optional)** Defaults to 1 if you set APN above. Ignored if you set no APN above.
**SIM PIN** Enter the SIM PIN if your service provider requires it. Leave blank if not required.
**SIM PIN wait** Time to wait for SIM to discover network after PIN is sent to SIM (seconds).
**Init String** Enter the modem initialization string here. Do not include the "AT" string at the beginning of the command.
Many modern USB 3G modems don't need an initialization string.
**Connection Timeout** Enter timeout in seconds for connection to be established (sec.) Default is 45 sec.
**Uptime Logging** This option causes cumulative uptime to be recorded and displayed on the Status Interfaces page.
**Dial On Demand** This option causes the interface to operate in dial-on-demand mode.
Do not enable if you want your link to be always up. The interface is configured, but the actual
connection of the link is delayed until qualifying outgoing traffic is detected.
**Idle Timeout** (seconds) Default is 0, which disables the timeout feature. If no incoming or outgoing packets are transmitted
for the entered number of seconds the connection is brought down.
When the idle timeout occurs, if the dial-on-demand option is enabled, mpd goes back into dial-on-demand mode.
Otherwise, the interface is brought down and all associated routes removed.
**Compression** This option enables Van Jacobson TCP header compression, which saves several bytes per TCP data packet.
You almost always want this option. This compression ineffective for TCP connections with enabled modern extensions
like time stamping or SACK, which modify TCP options between sequential packets.
**TCPmssFix** This option causes mpd to adjust incoming and outgoing TCP SYN segments so that the requested maximum segment
size is not greater than the amount allowed by the interface MTU. This is necessary in many setups to avoid problems
caused by routers that drop ICMP Datagram Too Big messages. Without these messages, the originating machine sends data,
it passes the rogue router then hits a machine that has an MTU that is not big enough for the data.
Because the IP Don't Fragment option is set, this machine sends an ICMP Datagram Too Big message back to the originator
and drops the packet. The rogue router drops the ICMP message and the originator never gets to discover that
it must reduce the fragment size or drop the IP Don't Fragment option from its outgoing data.
**ShortSeq** This option is only meaningful if multi-link PPP is negotiated. It proscribes shorter multi-link fragment headers,
saving two bytes on every frame. It is not necessary to disable this for connections that are not multi-link.
**ACFComp** Address and control field compression. This option only applies to asynchronous link types. It saves two bytes per frame.
**ProtoComp** Protocol field compression. This option saves one byte per frame for most frames.
========================================= ====================================================================================
.. tab:: PPPoE (Point-to-Point Protocol over Ethernet)
Encapsulates PPP frames within Ethernet frames, enabling authentication and connection management
over broadband connections like DSL. Typically used with ISPs for user authentication.
========================================= ====================================================================================
**Option** **Description**
========================================= ====================================================================================
**Link interfaces** Select one parent interface for PPP encapsulation.
**Description** You may enter a description here for your reference. Description will appear in the "Interfaces Assign" select lists
**Username** Enter your username for CHAP authentication.
**Password** Enter your password for CHAP authentication.
**Service name** This field can usually be left empty unless specified by the provider.
**Host-Uniq** This field can usually be left empty unless specified by the provider.
========================================= ====================================================================================
.. Note:: Check the PPP tab for all advanced options.
.. tab:: PPTP (Point-to-Point Tunneling Protocol)
A VPN protocol that uses PPP to encapsulate network packets and secure data transmission.
While widely supported, PPTP is considered insecure due to weak encryption mechanisms.
========================================= ====================================================================================
**Option** **Description**
========================================= ====================================================================================
**Link interfaces** Select one parent interface for PPP encapsulation.
**Description** You may enter a description here for your reference. Description will appear in the "Interfaces Assign" select lists
**Username** Enter your username for CHAP authentication.
**Password** Enter your password for CHAP authentication.
========================================= ====================================================================================
.. Note:: Check the PPP tab for all advanced options.
.. tab:: L2TP (Layer 2 Tunneling Protocol)
An extension of PPTP that does not provide encryption on its own but was often paired with IPsec
for secure tunneling. Used for VPN connections and remote access setups.
.. Note:: Check the PPTP and PPP tab for all options.
.. Note:: The ``ppp`` log files can be found in :menuselection:`System --> Log Files --> General`.
Read `PPPoE ISP Setup </manual/how-tos/pppoe_isp_setup.html>`_ for an example configuration of PPPoE with VLAN Tag for an ISP connection.