docs: OpenBSD Man Pages Added

1 files changed, 248 insertions, 0 deletions

diff --git a/static/openbsd/man4/pppoe.4 b/static/openbsd/man4/pppoe.4
new file mode 100644
index 00000000..ca0cd209
--- /dev/null
+++ b/static/openbsd/man4/pppoe.4
@@ -0,0 +1,248 @@
+.\"	$OpenBSD: pppoe.4,v 1.36 2022/05/27 15:45:02 jmc Exp $
+.\"	$NetBSD: pppoe.4,v 1.26 2003/10/02 07:06:36 wiz Exp $
+.\"
+.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Martin Husemann <martin@NetBSD.org>.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd $Mdocdate: May 27 2022 $
+.Dt PPPOE 4
+.Os
+.Sh NAME
+.Nm pppoe
+.Nd PPP Over Ethernet protocol network interface
+.Sh SYNOPSIS
+.Cd "pseudo-device pppoe"
+.Sh DESCRIPTION
+The
+.Nm
+interface encapsulates
+.Em Point-to-Point Protocol (PPP)
+packets inside Ethernet frames as defined by RFC 2516.
+.Pp
+This is often used to connect a router via a DSL modem to
+an access concentrator.
+The
+.Nm
+interface does not by itself transmit or receive frames,
+but needs an Ethernet interface to do so.
+This Ethernet interface is connected to the
+.Nm
+interface via
+.Xr ifconfig 8 .
+The Ethernet interface needs to be marked UP, but does not need to have an
+IP address.
+.Pp
+There are two basic modes of operation, controlled via the
+.Em link1
+switch.
+The default mode,
+.Em link1
+not being set, tries to keep the configured session open all the
+time.
+If the session is disconnected, a new connection attempt is started
+immediately.
+The
+.Dq dial on demand
+mode, selected by setting
+.Em link1 ,
+only establishes a connection when data is being sent to the interface.
+.Pp
+Before a
+.Nm
+interface is usable, it needs to be configured.
+The following steps are necessary:
+.Bl -bullet
+.It
+Create the interface.
+.It
+Connect an Ethernet interface.
+This interface is used for the physical communication.
+As noted above it must be marked UP, but need not have an IP address.
+.It
+Configure authentication.
+The PPP session needs to identify the client to the peer.
+For more details on the available options see
+.Xr ifconfig 8 .
+.It
+If using IPv6, configure a link-local address.
+.El
+.Pp
+This all is typically accomplished using an
+.Pa /etc/hostname.pppoe0
+file.
+A typical file looks like this:
+.Bd -literal -offset indent
+inet 0.0.0.0 255.255.255.255 NONE \e
+	pppoedev em0 authproto pap \e
+	authname 'testcaller' authkey 'donttell' up
+dest 0.0.0.1
+inet6 eui64
+!/sbin/route add default -ifp pppoe0 0.0.0.1
+!/sbin/route add -inet6 default -ifp pppoe0 fe80::%pppoe0
+.Ed
+.Pp
+The physical interface must also be marked
+.Ql up :
+.Bd -literal -offset indent
+# echo "up" > /etc/hostname.em0
+.Ed
+.Pp
+Since this is a PPP interface, the addresses assigned to the interface
+may change during PPP negotiation.
+In the above example, 0.0.0.0 and 0.0.0.1 serve as placeholders for
+dynamic address configuration.
+.Pp
+If the local address is set to wildcard address 0.0.0.0, it will
+be changed to an address suggested by the peer.
+.Pp
+If the destination address is set to a wildcard address in the range
+from 0.0.0.1 to 0.0.0.255, it will be changed to an address suggested
+by the peer, and if a default route which uses this interface exists
+the gateway will be changed to the suggested address as well.
+.Pp
+Otherwise, PPP negotiation will only agree to exactly the IPv4 addresses
+which are configured on the interface.
+.Sh KERNEL OPTIONS
+.Nm
+does not interfere with other PPPoE implementations
+running on the same machine.
+However under some circumstances
+(such as after a crash or power failure)
+the peer device might initially refuse to
+reestablish a new PPPoE connection
+because there is already an open session.
+This would be indicated by the client sending a high number of PADI packets
+before successfully connecting.
+The
+.Nm
+driver can be told to kill all unknown PPPoE sessions
+by sending a PADT packet to explicitly terminate the old session.
+Add the following to the kernel config file:
+.Pp
+.Dl option PPPOE_TERM_UNKNOWN_SESSIONS
+.Sh PPPOE AND MTU/MSS
+PPPoE has an 8-byte header.
+When run over a network interface with the
+standard Ethernet maximum transmission unit (MTU) of 1500 bytes,
+this reduces the maximum available MTU to 1492.
+.Nm
+sets the default MTU to this value.
+Unfortunately issues can occur when the path between
+the two endpoints of a TCP connection are not able to carry
+same sized packets,
+leading to possible packet fragmentation and sometimes packet loss.
+In that case the maximum packet size can be set using the
+.Cm max-mss
+option in
+.Xr pf.conf 5 .
+For example:
+.Pp
+.Dl match on pppoe0 scrub (max-mss 1440)
+.Sh MTU/MSS NEGOTIATION
+When using a PPPoE device configured for a higher MTU ("jumbo frames"),
+the MTU for the
+.Nm
+device can also be raised.
+In this case
+.Nm
+attempts to negotiate the higher size with the other PPPoE endpoint
+using the RFC 4638 protocol.
+This can allow standard Ethernet packet sizes (1500 bytes)
+to be carried over PPPoE.
+For example, in
+.Pa /etc/hostname.pppoe0 :
+.Bd -literal -offset indent
+inet 0.0.0.0 255.255.255.255 NONE mtu 1500 \e
+	pppoedev em0 authproto pap \e
+	authname 'testcaller' authkey 'donttell' up
+dest 0.0.0.1
+!/sbin/route add default -ifp pppoe0 0.0.0.1
+.Ed
+.Pp
+The physical interface would also have to be configured correspondingly:
+.Bd -literal -offset indent
+# echo "up mtu 1508" > /etc/hostname.em0
+.Ed
+.Pp
+However, RFC 4638 negotiation only takes into account the MTU configured
+on the endpoints, not the maximum MTU supported on the path between them.
+If the path cannot pass the larger Ethernet frames, negotiation will succeed
+but the larger frames will be dropped.
+For this reason it is important to test the connection with large packets
+when enabling a higher MTU.
+.Sh SEE ALSO
+.Xr sppp 4 ,
+.Xr hostname.if 5 ,
+.Xr pf.conf 5 ,
+.Xr ifconfig 8
+.Sh STANDARDS
+.Rs
+.%A L. Mamakos
+.%A K. Lidl
+.%A J. Evarts
+.%A D. Carrel
+.%A D. Simone
+.%A R. Wheeler
+.%D February 1999
+.%R RFC 2516
+.%T A Method for Transmitting PPP Over Ethernet (PPPoE)
+.Re
+.Pp
+.Rs
+.%A P. Arberg
+.%A D. Kourkouzelis
+.%A M. Duckett
+.%A T. Anschutz
+.%A J. Moisand
+.%D September 2006
+.%R RFC 4638
+.%T Accommodating a Maximum Transit Unit/Maximum Receive Unit (MTU/MRU) Greater Than 1492 in the Point-to-Point Protocol over Ethernet (PPPoE)
+.Re
+.Sh HISTORY
+The
+.Nm
+device first appeared in
+.Ox 3.7 .
+.Sh BUGS
+This implementation is client side only.
+.Pp
+It is important to specify
+.Dq Li netmask 255.255.255.255
+to
+.Xr ifconfig 8 .
+If the netmask is unspecified, it will be set to 8 when 0.0.0.0 is
+configured to the interface, and it will persist after negotiation.
+.Pp
+The presence of a
+.Xr mygate 5
+file will interfere with the routing table.
+Make sure this file is either empty or does not exist.
+.Pp
+Two
+.Nm
+interfaces configured with the same wildcard destination address
+cannot share a routing table.