'\" te
.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH pppoec 1M "9 Jan 2002" "SunOS 5.11" "System Administration Commands"
.SH NAME
pppoec \- PPPoE chat utility
.SH SYNOPSIS
.LP
.nf
\fBpppoec\fR [\fB-o\fImillisecs\fR\fR] [\fB-s\fR\fImillisecs\fR] [\fB-v\fR] \fIdevice\fR 
     [\fIservice\fR [ [except]\fIserver\fR... [only]]]
.fi

.LP
.nf
\fBpppoec\fR [\fB-o\fImillisecs\fR\fR] [\fB-v\fR] \fB-i\fR [\fIdevice\fR]
.fi

.SH DESCRIPTION
.sp
.LP
The \fBpppoec\fR utility implements the client-side negotiation of PPPoE. It is
intended to be used with the \fBpppd\fR(1M) \fBconnect\fR option, in the same
manner as the \fBchat\fR(1M) utility is used for asynchronous dial-up PPP.
.sp
.LP
When given with the \fB-i\fR flag, \fBpppoec\fR sends out a broadcast query on
the given interface named by the \fIdevice\fR parameter. You can specify no
other arguments in this mode. All responding PPPoE servers and the offered
services are displayed on standard output.
.sp
.LP
Otherwise, when given without the \fB-i\fR flag, \fBpppoec\fR does the full
PPPoE client-side negotiation. The \fIdevice\fR parameter is the intended
Ethernet interface, and must already be plumbed with \fBsppptun\fR(1M). The
optional \fIservice\fR parameter specifies a particular service desired; other
offered services will be ignored. The optional \fIserver\fR parameter specifies
a specific server desired. You can specify \fIserver\fR as an Ethernet address
in the usual x:x:x:x:x:x format (with "\fB*\fR" in any of the six byte
positions interpreted to mean "any"), or as a symbolic name resolved through
\fB/etc/ethers\fR (or NIS), or as a PPPoE access concentrator name. The sense
of the match (true or false) can be inverted by specifying the keyword
\fBexcept\fR before this string. This parameter can be specified more than
once, and the first match is taken.
.sp
.LP
If you specify the \fIserver\fR parameter, then the selected servers become
"preferred." If no preferred server responds, then the first responding server
is used instead. To exclude non-matching servers entirely, append the keyword
\fBonly\fR.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.mk
.na
\fB\fB-i\fR\fR
.ad
.RS 6n
.rt  
Sends out broadcast query over interface specified by \fIdevice\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-o\fR\fR
.ad
.RS 6n
.rt  
Sets the initial wait time in milliseconds for PADO from the server before PADI
is retried. The default is 500 milliseconds for normal operation, or 3000
milliseconds (3 seconds) for inquiry (\fB-i\fR) mode.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-s\fR\fR
.ad
.RS 6n
.rt  
Sets the initial wait time in milliseconds for PADS from the server before PADR
is retried. The default is 2000 milliseconds (2 seconds).
.RE

.sp
.ne 2
.mk
.na
\fB\fB-v\fR\fR
.ad
.RS 6n
.rt  
Displays verbose progress messages, including all PPPoE messages sent, and all
state machine transitions.
.RE

.sp
.LP
You normally do not need to adjust the parameters set with \fB-o\fR and
\fB-s\fR. They are provided for coping with unusually slow servers.
.SH OPERANDS
.sp
.LP
The following operands are supported:
.sp
.ne 2
.mk
.na
\fB\fIdevice\fR\fR
.ad
.RS 11n
.rt  
plumbed Ethernet interface
.RE

.sp
.ne 2
.mk
.na
\fB\fIserver\fR\fR
.ad
.RS 11n
.rt  
preferred server or, if you specify \fBonly\fR, the specified server
.RE

.sp
.ne 2
.mk
.na
\fB\fIservice\fR\fR
.ad
.RS 11n
.rt  
desired service; other available services are ignored
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRConnecting to Any Service on \fBhme0\fR
.sp
.LP
The following command enables you to connect to any PPPoE service on
\fBhme0\fR:

.sp
.in +2
.nf
# /usr/bin/pppd sppptun plugin pppoe.so \
connect "/usr/lib/inet/pppoec hme0" debug
.fi
.in -2
.sp

.sp
.LP
Often, a command such as the preceding is specified in an \fB/etc/ppp/peers\fR
file instead. For example, enter the following in \fB/etc/ppp/peers/myisp\fR:

.sp
.in +2
.nf
sppptun
plugin pppoe.so
connect "/usr/lib/inet/pppoec hme0"
debug
.fi
.in -2
.sp

.sp
.LP
To invoke the PPP connection described in the file, enter:

.sp
.in +2
.nf
% /usr/bin/pppd call myisp
.fi
.in -2
.sp

.sp
.LP
Note that, because the \fB/etc/ppp/peers\fR files are considered privileged by
\fBpppd\fR, you need not be root to invoke the preceding command.

.LP
\fBExample 2 \fRConnecting to a Particular Service
.sp
.LP
A more complex example: on \fBhme0\fR, connect to only the \fBinternet\fR
service offered by PPPoE servers with access concentrator name \fBisp\fR, but
not to any Ethernet addresses starting with \fB40:0:1a\fR.

.sp
.in +2
.nf
# \fB/usr/lib/inet/pppoec hme0 internet except 40:0:1a:*:*:* isp only\fR
.fi
.in -2
.sp

.sp
.LP
Note that the \fBexcept 40:0:1a:*:*:*\fR filter must come before \fBisp\fR,
because the filters are first-match.

.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.mk
.na
\fB\fB0\fR \fR
.ad
.RS 6n
.rt  
Successful completion.
.RE

.sp
.ne 2
.mk
.na
\fB>\fB0\fR\fR
.ad
.RS 6n
.rt  
An error occurred.
.RE

.SH FILES
.sp
.ne 2
.mk
.na
\fB\fB/usr/lib/inet/pppoec\fR \fR
.ad
.RS 27n
.rt  
executable command
.RE

.sp
.ne 2
.mk
.na
\fB\fB/dev/sppptun\fR\fR
.ad
.RS 27n
.rt  
Solaris PPP tunneling device driver.
.RE

.sp
.ne 2
.mk
.na
\fB\fB/etc/ppp/connect-errors\fR\fR
.ad
.RS 27n
.rt  
usual location of error output (see DIAGNOSTICS, below)
.RE

.SH SEE ALSO
.sp
.LP
\fBpppd\fR(1M), \fBsppptun\fR(1M), \fBpppoed\fR(1M), \fBsppptun\fR(7M)
.sp
.LP
\fIRFC 2516, Method for Transmitting PPP Over Ethernet (PPPoE)\fR, Mamakos et
al, February 1999
.SH DIAGNOSTICS
.sp
.LP
Error messages are written to standard error, which is normally redirected by
\fBpppd\fR to \fB/etc/ppp/connect-errors\fR. The errors can also be redirected
to \fBpppd\fR's standard output by using the \fBupdetach\fR option.
.sp
.LP
If you specify the \fB-v\fR, verbose progress messages are displayed, including
all PPPoE messages sent, and all state machine transitions. Specifying the
\fBupdetach\fR or \fBnodetach\fR \fBpppd\fR option is helpful when using
verbose mode.