.\" $OpenBSD: pppoe.8,v 1.21 2007/05/31 19:20:28 jmc Exp $ .\" .\" Copyright (c) 2000 Network Security Technologies, Inc. .\" (http://www.netsec.net) .\" .\" 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 AUTHOR ``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 AUTHOR 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 31 2007 $ .Dt PPPOE 8 .Os .Sh NAME .Nm pppoe .Nd PPP Over Ethernet translator .Sh SYNOPSIS .Nm pppoe .Op Fl sv .Op Fl i Ar interface .Op Fl n Ar service .Op Fl p Ar system .Sh DESCRIPTION The .Nm pppoe program can, with the help of .Xr ppp 8 , act as a server or client for running PPP Over Ethernet. .Pp The options are as follows: .Bl -tag -width Ds .It Fl i Ar interface Specify the interface that .Nm is to use, which should be a real Ethernet interface (not a virtual device like .Xr tun 4 ) . If this option is not specified, .Nm will use the first Ethernet interface that is up and running. .It Fl n Ar service Use .Ar service as the service name when negotiating with the server. By default, the client will ask for any service, and expect the server to respond with the same. .It Fl p Ar system This argument is passed, uninterpreted, to .Xr ppp 8 . It can be used to specify the configuration data to be used for PPP Over Ethernet connections. This option is only used in server mode. .It Fl s If this option is specified, .Nm will run as a server. Otherwise, .Nm runs as a client. .It Fl v For each use of the flag, the verbosity of .Nm pppoe increases. .El .Sh CLIENT SETUP Configuring the client involves setting up the configuration file for .Xr ppp 8 . The following statements must be included in the file for the specified .Ar system (or ``default'' if no .Ar system is specified): .Bd -literal -offset indent set device "!/usr/sbin/pppoe" set mtu max 1492 set mru max 1492 set speed sync disable acfcomp protocomp deny acfcomp .Ed .Pp The .Em "set device" line tells .Nm ppp to use .Nm pppoe program for input and output instead of using a serial port or other network connection. The .Nm mtu and .Nm mru must be set to 1492 to leave room in the outgoing Ethernet packet for the .Nm pppoe headers. The .Em "set speed sync" line tells .Nm ppp to use synchronous encoding for the packets sent between it and .Nm pppoe . According to RFC 2516, protocol compression, .Em protocomp , is not recommended, so it is disabled, but not denied. On the other hand, address and control field compression, .Em acfcomp , must be disabled and denied. .Pp Additionally, the authentication mechanism for the connection must be specified as well as any other parameters. .Sh EXAMPLE CONFIGURATION Given a machine with one Ethernet interface, .Em xl0 , the first thing that must be done is to bring the interface up: .Bd -literal -offset indent # ifconfig xl0 up .Ed .Pp This can be done automatically during boot with a .Pa /etc/hostname.xl0 file, see .Xr hostname.if 5 for details. .Pp Next, a .Pa /etc/ppp/ppp.conf file must be created. Below is a minimal PPPoE style configuration, see .Xr ppp 8 for more options. .Bd -literal -offset indent default: set log Phase Chat LCP IPCP CCP tun command pppoe: set device "!/usr/sbin/pppoe -i xl0" set mtu max 1492 set mru max 1492 set speed sync disable acfcomp protocomp deny acfcomp set authname "myUsername" set authkey "myPassword" .Ed .Pp The .Nm default section sets up some helpful information to log while getting started, and the .Nm pppoe section sets the required fields for a PPPoE connection as well as the username and password to use to authenticate to the service provider. .Pp Once the .Pa /etc/ppp/ppp.conf file is set up, it is just a matter of setting .Xr ppp 8 into action: .Bd -literal -offset indent # ppp pppoe Working in interactive mode Using interface: tun0 ppp ON deepthought> dial Ppp ON deepthought> PPp ON deepthought> PPP ON deepthought> .Ed .Pp The userland .Xr ppp 8 daemon has many options for configuration, like adding default routes, network address translation, automatically using remote DNS servers, automatic dialing, etc. Please see .Xr ppp 8 for details. .Pp Several .Xr ppp 8 options are particularly helpful when used with .Nm pppoe . .Bl -tag -width Ds .It enable lqr / accept lqr Enable and accept link quality requests, which can be used to detect whether the link has gone down. .It enable mssfixup Allow .Xr ppp 8 to adjust the maximum segment size on outgoing SYN packets. .El .Sh SEE ALSO .Xr pppoe 4 , .Xr tun 4 , .Xr hostname.if 5 , .Xr ifconfig 8 , .Xr ppp 8 .Rs .%T RFC 2516 A Method for Transmitting PPP Over Ethernet (PPPoE) .%A L. Mamakos, et al. .Re .Sh HISTORY This implementation of .Nm pppoe first appeared in .Ox 2.8 . .Sh AUTHORS .An -nosplit The .Nm pppoe program was written by .An Jason L. Wright .Aq jason@thought.net of .An Network Security Technologies, Inc. .Aq http://www.netsec.net . .Sh BUGS This software runs completely in user mode. As such it will have much more overhead than a kernel implementation. .Pp The .Ar service is not currently used by the server code.