| blob | 63e6f9a20bc4ed5b2320d0f54f39ca21835c6093 |
1 .\" $NetBSD: pppoectl.8,v 1.24 2005/02/19 18:26:09 christos Exp $
2 .\"
3 .\" Copyright (C) 1997 by Joerg Wunsch, Dresden
4 .\" All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\"
15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) ``AS IS'' AND ANY EXPRESS
16 .\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
17 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
18 .\" DISCLAIMED. IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT,
19 .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
20 .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
21 .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
23 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
24 .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
25 .\" POSSIBILITY OF SUCH DAMAGE.
26 .\"
27 .\" From: spppcontrol.1,v 1.1.1.1 1997/10/11 11:30:30 joerg Exp
28 .\"
29 .\" $Id: pppoectl.8,v 1.25 2009/03/09 19:24:27 joerg Exp $
30 .\"
31 .\" last edit-date: [Thu Aug 31 10:47:33 2000]
32 .\"
33 .Dd October 2, 2003
34 .Dt PPPOECTL 8
35 .Os
36 .Sh NAME
37 .Nm pppoectl ,
38 .Nm ipppctl
39 .Nd "display or set parameters for an pppoe or isdn ppp (ippp) interface"
40 .Sh SYNOPSIS
41 .Nm pppoectl
42 .Op Fl v
43 .Ar ifname
44 .Op Ar parameter Ns Op \&= Ns Ar value
45 .Op Ar ...
46 .Pp
47 .Nm ipppctl
48 .Op Fl v
49 .Ar ifname
50 .Op Ar parameter Ns Op \&= Ns Ar value
51 .Op Ar ...
52 .Pp
53 .Nm pppoectl
54 .Fl e Ar ethernet-ifname
55 .Op Fl s Ar service-name
56 .Op Fl a Ar access-concentrator-name
57 .Op Fl d
58 .Op Fl n Ar 1 \&| 2
59 .Ar ifname
60 .Pp
61 .Nm pppoectl
62 .Fl f Ar config-file
63 .Ar ifname
64 .Op Ar ...
65 .Sh DESCRIPTION
66 There are two basic modes of operation: configuring security related
67 parameters and attaching a PPPoE interface to its ethernet interface,
68 optionally passing in additional parameters for the PPPoE encapsulation.
69 .Pp
70 The later usage is indicated by the presence of the
71 .Fl e
72 option, which takes the name of the ethernet interface as its argument.
73 .Pp
74 .Bl -tag -width indent
75 .It Fl e
76 specifies the ethernet interface used to communicate with the
77 access concentrator (typically via a DSL modem).
78 .It Fl a
79 specifies the name of the access concentrator.
80 .It Fl s
81 specifies the name of the service connected to.
82 .It Fl d
83 dump the current connection state information (this parameter is typically
84 used alone, for informational purposes, not during interface configuration).
85 .It Fl n Ar 1 \&| 2
86 print the IP address of the primary or secondary DNS name server for this
87 PPP connection.
88 This is only available if DNS query is enabled, see
89 .Ar query-dns .
90 .It Fl f
91 parse
92 .Ar config-file
93 for
94 .Ar parameter Ns Op \&= Ns Ar value
95 pairs, one per line, as if they had been specified on the command line.
96 This allows the password to be not passed as a command line argument.
97 Unless escaped by \e, comments starting with # to the end of the current line
98 are ignored.
99 .El
100 .Pp
101 Typically, not both the access concentrator name and the service name are
102 specified.
103 .Pp
104 The
105 .Xr ippp 4
106 or the
107 .Xr pppoe 4
108 drivers require a number of additional arguments or optional
109 parameters besides the settings that can be adjusted with
110 .Xr ifconfig 8 .
111 These are things like authentication protocol parameters, but also
112 other tunable configuration variables.
113 The
114 .Nm
115 utility can be used to display the current settings, or adjust these
116 parameters as required.
117 .Pp
118 For whatever intent
119 .Nm
120 is being called, at least the parameter
121 .Ar ifname
122 needs to be specified, naming the interface for which the settings
123 are to be performed or displayed.
124 Use
125 .Xr ifconfig 8
126 or
127 .Xr netstat 1
128 to see which interfaces are available.
129 .Pp
130 If no other parameter is given,
131 .Nm
132 will just list the current settings for
133 .Ar ifname
134 and exit.
135 The reported settings include the current PPP phase the
136 interface is in, which can be one of the names
137 .Em dead ,
138 .Em establish ,
139 .Em authenticate ,
140 .Em network ,
141 or
142 .Em terminate .
143 If an authentication protocol is configured for the interface, the
144 name of the protocol to be used, as well as the system name to be used
145 or expected will be displayed, plus any possible options to the
146 authentication protocol if applicable.
147 Note that the authentication
148 secrets (sometimes also called
149 .Em keys )
150 are not being returned by the underlying system call, and are thus not
151 displayed.
152 .Pp
153 If any additional parameter is supplied, superuser privileges are
154 required, and the command works in
155 .Ql set
156 mode.
157 This is normally done quietly, unless the option
158 .Fl v
159 is also enabled, which will cause a final printout of the settings as
160 described above once all other actions have been taken.
161 Use of this mode will be rejected if the interface is currently in any
162 other phase than
163 .Em dead .
164 Note that you can force an interface into
165 .Em dead
166 phase by calling
167 .Xr ifconfig 8
168 with the parameter
169 .Ql down .
170 .Pp
171 The currently supported parameters include:
172 .Bl -tag -width xxxxxxxxxxxxxxxxxxxxxxxxx
173 .It Ar authproto Ns \&= Ns Em protoname
174 Set both his and my authentication protocol to
175 .Em protoname .
176 The protocol name can be one of
177 .Ql chap ,
178 .Ql pap ,
179 or
180 .Ql none .
181 In the latter case, the use of an authentication protocol will be
182 turned off for the named interface.
183 This has the side-effect of
184 clearing the other authentication-related parameters for this
185 interface as well (i.
186 e., system name and authentication secret will
187 be forgotten).
188 .It Ar myauthproto Ns \&= Ns Em protoname
189 Same as above, but only for my end of the link.
190 I.e., this is the protocol when remote is authenticator,
191 and I am the peer required to authenticate.
192 .It Ar hisauthproto Ns \&= Ns Em protoname
193 Same as above, but only for his end of the link.
194 .It Ar myauthname Ns \&= Ns Em name
195 Set my system name for the authentication protocol.
196 .It Ar hisauthname Ns \&= Ns Em name
197 Set his system name for the authentication protocol.
198 For CHAP, this will only be used as a hint, causing
199 a warning message if remote did supply a different name.
200 For PAP, it's the name remote must use to
201 authenticate himself (in connection with his secret).
202 .It Ar myauthsecret Ns \&= Ns Em secret
203 Set my secret (key, password) for use in the authentication phase.
204 For CHAP, this will be used to compute the response hash value, based
205 on remote's challenge.
206 For PAP, it will be transmitted as plaintext
207 together with the system name.
208 Don't forget to quote the secrets from
209 the shell if they contain shell metacharacters (or whitespace).
210 .It Ar myauthkey Ns \&= Ns Em secret
211 Same as above.
212 .It Ar hisauthsecret Ns \&= Ns Em secret
213 Same as above, to be used if we are authenticator and the remote peer
214 needs to authenticate.
215 .It Ar hisauthkey Ns \&= Ns Em secret
216 Same as above.
217 .It Ar callin
218 Require remote to authenticate himself only when he's calling in, but
219 not when we are caller.
220 This is required for some peers that do not
221 implement the authentication protocols symmetrically (like Ascend
222 routers, for example).
223 .It Ar always
224 The opposite of
225 .Ar callin .
226 Require remote to always authenticate, regardless of which side is
227 placing the call.
228 This is the default, and will not be explicitly displayed in
229 .Ql list
230 mode.
231 .It Ar norechallenge
232 Only meaningful with CHAP.
233 Do not re-challenge peer once the initial
234 CHAP handshake was successful.
235 Used to work around broken peer implementations that can't grok
236 being re-challenged once the connection is up.
237 .It Ar rechallenge
238 With CHAP, send re-challenges at random intervals while the connection
239 is in network phase.
240 (The intervals are currently in the range of 300
241 through approximately 800 seconds.)
242 This is the default, and will not be explicitly displayed in
243 .Ql list
244 mode.
245 .It Ar idle-timeout Ns \&= Ns Em idle-seconds
246 For services that are charged by connection time the interface can optionally
247 disconnect after a configured idle time.
248 If set to 0, this feature is disabled.
249 Note: for ISDN devices, it is preferable to use the
250 .Xr isdnd 8
251 based timeout mechanism, as isdnd can predict the next charging unit for
252 ISDN connections and optimize the timeout with this information.
253 .It Ar lcp-timeout Ns \&= Ns Em timeout-value
254 Allows to change the value of the LCP timeout.
255 The default value of the LCP timeout is currently set to 1 second.
256 The timeout-value must be specified in milliseconds.
257 .It Ar max-noreceive Ns \&= Ns Em sec
258 Sets the number of seconds after last reception of data from the peer before
259 the line state is probed by sending LCP echo requests.
260 The
261 .Em sec
262 interval is not used verbatim, the first echo request might be delayed upto
263 10 seconds after the configured interval.
264 .It Ar max-alive-missed Ns \&= Ns Em count
265 Sets the number of unanswered LCP echo requests that we will tolerate before
266 considering a connection to be dead.
267 LCP echo requests are sent in 10 seconds interval after the configured
268 .Em max-noreceive
269 interval has passed with no data received from the peer.
270 .It Ar max-auth-failure Ns \&= Ns Em count
271 Since some ISPs disable accounts after too many unsuccessful authentication
272 attempts, there is a maximum number of authentication failures before we will
273 stop retrying without manual intervention.
274 Manual intervention is either changing the authentication data
275 (name, password) or setting the maximum retry count.
276 If
277 .Em count
278 is set to
279 .Em 0
280 this feature is disabled.
281 .It Ar clear-auth-failure
282 If an authentication failure has been caused by remote problems and you want
283 to retry connecting using unchanged local settings, this command can be used
284 to reset the failure count to zero.
285 .It Ar query-dns Ns \&= Ns Em flags
286 During PPP protocol negotiation we can query the peer
287 for addresses of two name servers.
288 If
289 .Ar flags
290 is
291 .Em 1
292 only the first server address will be requested, if
293 .Ar flags
294 is
295 .Em 2
296 the second will be requested.
297 Setting
298 .Ar flags
299 to
300 .Em 3
301 queries both.
302 .Pp
303 The result of the negotiation can be retrieved with the
304 .Fl n
305 option.
306 .El
307 .Sh EXAMPLES
308 .Bd -literal
309 # ipppctl ippp0
310 ippp0: phase=dead
311 myauthproto=chap myauthname="uriah"
312 hisauthproto=chap hisauthname="ifb-gw" norechallenge
313 lcp timeout: 3.000 s
314 .Ed
315 .Pp
316 Display the settings for ippp0.
317 The interface is currently in
318 .Em dead
319 phase, i.e. the LCP layer is down, and no traffic is possible.
320 Both ends of the connection use the CHAP protocol,
321 my end tells remote the system name
322 .Ql uriah ,
323 and remote is expected to authenticate by the name
324 .Ql ifb-gw .
325 Once the initial CHAP handshake was successful, no further CHAP
326 challenges will be transmitted.
327 There are supposedly some known CHAP
328 secrets for both ends of the link which are not being shown.
329 .Pp
330 .Bd -literal
331 # ipppctl ippp0 \e
332 authproto=chap \e
333 myauthname=uriah myauthsecret='some secret' \e
334 hisauthname=ifb-gw hisauthsecret='another' \e
335 norechallenge
336 .Ed
337 .Pp
338 A possible call to
339 .Nm
340 that could have been used to bring the interface into the state shown
341 by the previous example.
342 .Pp
343 The following example is the complete sequence of commands to bring
344 a PPPoE connection up:
345 .Bd -literal
346 # Need ethernet interface UP (or it won't send any packets)
347 ifconfig ne0 up
349 # Let pppoe0 use ne0 as its ethernet interface
350 pppoectl -e ne0 pppoe0
352 # Configure authentication
353 pppoectl pppoe0 \\
354 myauthproto=pap \\
355 myauthname=XXXXX \\
356 myauthsecret=YYYYY \\
357 hisauthproto=none
359 # Configure the pppoe0 interface itself. These addresses are magic,
360 # meaning we don't care about either address and let the remote
361 # ppp choose them.
362 ifconfig pppoe0 0.0.0.0 0.0.0.1 netmask 0xffffffff up
363 .Ed
364 .Sh SEE ALSO
365 .Xr netstat 1 ,
366 .Xr ippp 4 ,
367 .Xr pppoe 4 ,
368 .Xr ifconfig 8 ,
369 .Xr ifwatchd 8
370 .Rs
371 .%A B. Lloyd
372 .%A W. Simpson
373 .%T "PPP Authentication Protocols"
374 .%O RFC 1334
375 .Re
376 .Rs
377 .%A W. Simpson, Editor
378 .%T "The Point-to-Point Protocol (PPP)"
379 .%O RFC 1661
380 .Re
381 .Rs
382 .%A W. Simpson
383 .%T "PPP Challenge Handshake Authentication Protocol (CHAP)"
384 .%O RFC 1994
385 .Re
386 .Rs
387 .%A L. Mamakos
388 .%A K. Lidl
389 .%A J. Evarts
390 .%A D. Carrel
391 .%A D. Simone
392 .%A R. Wheeler
393 .%T "A Method for Transmitting PPP Over Ethernet (PPPoE)"
394 .%O RFC 2516
395 .Re
396 .Sh HISTORY
397 The
398 .Nm
399 utility is based on the
400 .Ic spppcontrol
401 utility which appeared in
402 .Fx 3.0 .
403 .Sh AUTHORS
404 The program was written by
405 .ie t J\(:org Wunsch,
406 .el Joerg Wunsch,
407 Dresden, and modified for PPPoE support by Martin Husemann.