share/man/man8/pppoec.8

   1 '\" te
   2 .\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH PPPOEC 8 "Jan 9, 2002"
   7 .SH NAME
   8 pppoec \- PPPoE chat utility
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBpppoec\fR [\fB-o\fImillisecs\fR\fR] [\fB-s\fR\fImillisecs\fR] [\fB-v\fR] \fIdevice\fR
  13      [\fIservice\fR [ [except]\fIserver\fR... [only]]]
  14 .fi
  15
  16 .LP
  17 .nf
  18 \fBpppoec\fR [\fB-o\fImillisecs\fR\fR] [\fB-v\fR] \fB-i\fR [\fIdevice\fR]
  19 .fi
  20
  21 .SH DESCRIPTION
  22 .sp
  23 .LP
  24 The \fBpppoec\fR utility implements the client-side negotiation of PPPoE. It is
  25 intended to be used with the \fBpppd\fR(8) \fBconnect\fR option, in the same
  26 manner as the \fBchat\fR(8) utility is used for asynchronous dial-up PPP.
  27 .sp
  28 .LP
  29 When given with the \fB-i\fR flag, \fBpppoec\fR sends out a broadcast query on
  30 the given interface named by the \fIdevice\fR parameter. You can specify no
  31 other arguments in this mode. All responding PPPoE servers and the offered
  32 services are displayed on standard output.
  33 .sp
  34 .LP
  35 Otherwise, when given without the \fB-i\fR flag, \fBpppoec\fR does the full
  36 PPPoE client-side negotiation. The \fIdevice\fR parameter is the intended
  37 Ethernet interface, and must already be plumbed with \fBsppptun\fR(8). The
  38 optional \fIservice\fR parameter specifies a particular service desired; other
  39 offered services will be ignored. The optional \fIserver\fR parameter specifies
  40 a specific server desired. You can specify \fIserver\fR as an Ethernet address
  41 in the usual x:x:x:x:x:x format (with "\fB*\fR" in any of the six byte
  42 positions interpreted to mean "any"), or as a symbolic name resolved through
  43 \fB/etc/ethers\fR (or NIS), or as a PPPoE access concentrator name. The sense
  44 of the match (true or false) can be inverted by specifying the keyword
  45 \fBexcept\fR before this string. This parameter can be specified more than
  46 once, and the first match is taken.
  47 .sp
  48 .LP
  49 If you specify the \fIserver\fR parameter, then the selected servers become
  50 "preferred." If no preferred server responds, then the first responding server
  51 is used instead. To exclude non-matching servers entirely, append the keyword
  52 \fBonly\fR.
  53 .SH OPTIONS
  54 .sp
  55 .LP
  56 The following options are supported:
  57 .sp
  58 .ne 2
  59 .na
  60 \fB\fB-i\fR\fR
  61 .ad
  62 .RS 6n
  63 Sends out broadcast query over interface specified by \fIdevice\fR.
  64 .RE
  65
  66 .sp
  67 .ne 2
  68 .na
  69 \fB\fB-o\fR\fR
  70 .ad
  71 .RS 6n
  72 Sets the initial wait time in milliseconds for PADO from the server before PADI
  73 is retried. The default is 500 milliseconds for normal operation, or 3000
  74 milliseconds (3 seconds) for inquiry (\fB-i\fR) mode.
  75 .RE
  76
  77 .sp
  78 .ne 2
  79 .na
  80 \fB\fB-s\fR\fR
  81 .ad
  82 .RS 6n
  83 Sets the initial wait time in milliseconds for PADS from the server before PADR
  84 is retried. The default is 2000 milliseconds (2 seconds).
  85 .RE
  86
  87 .sp
  88 .ne 2
  89 .na
  90 \fB\fB-v\fR\fR
  91 .ad
  92 .RS 6n
  93 Displays verbose progress messages, including all PPPoE messages sent, and all
  94 state machine transitions.
  95 .RE
  96
  97 .sp
  98 .LP
  99 You normally do not need to adjust the parameters set with \fB-o\fR and
 100 \fB-s\fR. They are provided for coping with unusually slow servers.
 101 .SH OPERANDS
 102 .sp
 103 .LP
 104 The following operands are supported:
 105 .sp
 106 .ne 2
 107 .na
 108 \fB\fIdevice\fR\fR
 109 .ad
 110 .RS 11n
 111 plumbed Ethernet interface
 112 .RE
 113
 114 .sp
 115 .ne 2
 116 .na
 117 \fB\fIserver\fR\fR
 118 .ad
 119 .RS 11n
 120 preferred server or, if you specify \fBonly\fR, the specified server
 121 .RE
 122
 123 .sp
 124 .ne 2
 125 .na
 126 \fB\fIservice\fR\fR
 127 .ad
 128 .RS 11n
 129 desired service; other available services are ignored
 130 .RE
 131
 132 .SH EXAMPLES
 133 .LP
 134 \fBExample 1 \fRConnecting to Any Service on \fBhme0\fR
 135 .sp
 136 .LP
 137 The following command enables you to connect to any PPPoE service on
 138 \fBhme0\fR:
 139
 140 .sp
 141 .in +2
 142 .nf
 143 # /usr/bin/pppd sppptun plugin pppoe.so \
 144 connect "/usr/lib/inet/pppoec hme0" debug
 145 .fi
 146 .in -2
 147 .sp
 148
 149 .sp
 150 .LP
 151 Often, a command such as the preceding is specified in an \fB/etc/ppp/peers\fR
 152 file instead. For example, enter the following in \fB/etc/ppp/peers/myisp\fR:
 153
 154 .sp
 155 .in +2
 156 .nf
 157 sppptun
 158 plugin pppoe.so
 159 connect "/usr/lib/inet/pppoec hme0"
 160 debug
 161 .fi
 162 .in -2
 163 .sp
 164
 165 .sp
 166 .LP
 167 To invoke the PPP connection described in the file, enter:
 168
 169 .sp
 170 .in +2
 171 .nf
 172 % /usr/bin/pppd call myisp
 173 .fi
 174 .in -2
 175 .sp
 176
 177 .sp
 178 .LP
 179 Note that, because the \fB/etc/ppp/peers\fR files are considered privileged by
 180 \fBpppd\fR, you need not be root to invoke the preceding command.
 181
 182 .LP
 183 \fBExample 2 \fRConnecting to a Particular Service
 184 .sp
 185 .LP
 186 A more complex example: on \fBhme0\fR, connect to only the \fBinternet\fR
 187 service offered by PPPoE servers with access concentrator name \fBisp\fR, but
 188 not to any Ethernet addresses starting with \fB40:0:1a\fR.
 189
 190 .sp
 191 .in +2
 192 .nf
 193 # \fB/usr/lib/inet/pppoec hme0 internet except 40:0:1a:*:*:* isp only\fR
 194 .fi
 195 .in -2
 196 .sp
 197
 198 .sp
 199 .LP
 200 Note that the \fBexcept 40:0:1a:*:*:*\fR filter must come before \fBisp\fR,
 201 because the filters are first-match.
 202
 203 .SH EXIT STATUS
 204 .sp
 205 .LP
 206 The following exit values are returned:
 207 .sp
 208 .ne 2
 209 .na
 210 \fB\fB0\fR \fR
 211 .ad
 212 .RS 6n
 213 Successful completion.
 214 .RE
 215
 216 .sp
 217 .ne 2
 218 .na
 219 \fB>\fB0\fR\fR
 220 .ad
 221 .RS 6n
 222 An error occurred.
 223 .RE
 224
 225 .SH FILES
 226 .sp
 227 .ne 2
 228 .na
 229 \fB\fB/usr/lib/inet/pppoec\fR \fR
 230 .ad
 231 .RS 27n
 232 executable command
 233 .RE
 234
 235 .sp
 236 .ne 2
 237 .na
 238 \fB\fB/dev/sppptun\fR\fR
 239 .ad
 240 .RS 27n
 241 Solaris PPP tunneling device driver.
 242 .RE
 243
 244 .sp
 245 .ne 2
 246 .na
 247 \fB\fB/etc/ppp/connect-errors\fR\fR
 248 .ad
 249 .RS 27n
 250 usual location of error output (see DIAGNOSTICS, below)
 251 .RE
 252
 253 .SH SEE ALSO
 254 .sp
 255 .LP
 256 \fBpppd\fR(8), \fBsppptun\fR(8), \fBpppoed\fR(8), \fBsppptun\fR(7M)
 257 .sp
 258 .LP
 259 \fIRFC 2516, Method for Transmitting PPP Over Ethernet (PPPoE)\fR, Mamakos et
 260 al, February 1999
 261 .SH DIAGNOSTICS
 262 .sp
 263 .LP
 264 Error messages are written to standard error, which is normally redirected by
 265 \fBpppd\fR to \fB/etc/ppp/connect-errors\fR. The errors can also be redirected
 266 to \fBpppd\fR's standard output by using the \fBupdetach\fR option.
 267 .sp
 268 .LP
 269 If you specify the \fB-v\fR, verbose progress messages are displayed, including
 270 all PPPoE messages sent, and all state machine transitions. Specifying the
 271 \fBupdetach\fR or \fBnodetach\fR \fBpppd\fR option is helpful when using
 272 verbose mode.