path: root/usr.sbin/pppoe/pppoe.8

.\"	$OpenBSD: pppoe.8,v 1.25 2012/08/15 19:25:41 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: August 15 2012 $
.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 the
.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
.%R RFC 2516
.%T 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 Lk 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.