1.\" $NetBSD: pppoectl.8,v 1.11 2002/04/14 11:41:42 martin 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.11 2002/04/14 11:41:42 martin Exp $ 30.\" 31.\" last edit-date: [Thu Aug 31 10:47:33 2000] 32.\" 33.Dd December 11, 2001 34.Os 35.Dt PPPOECTL 8 36.Sh NAME 37.Nm pppoectl , 38.Nm ipppcontrol 39.Nd "display or set parameters for an pppoe or isdn ppp (ippp) interface" 40.Sh SYNOPSIS 41.Nm 42.Op Fl v 43.Ar ifname 44.Op Ar parameter Ns Op \&= Ns Ar value 45.Op Ar ... 46.Pp 47.Nm pppoectl 48.Fl e Ar ethernet-ifname 49.Op Fl s Ar service-name 50.Op Fl a Ar access-concentrator-name 51.Op Fl d 52.Op Fl n Ar 1 \&| 2 53.Ar ifname 54.Sh DESCRIPTION 55There are two basic modes of operation: configuring security related 56parameters and attaching a PPPoE interface to its ethernet interface, 57optionally passing in additional parameters for the PPPoE encapsulation. 58.Pp 59The later usage is indicated by the presence of the 60.Fl e 61option, which takes the name of the ethernet interface as its argument. 62.Pp 63.Bl -tag -width indent 64.It Fl e 65specifies the ethernet interface used to communicate with the 66access concentrator (typically via a DSL modem). 67.It Fl a 68specifies the name of the access concentrator. 69.It Fl s 70specifies the name of the service connected to. 71.It Fl d 72dump the current connection state information (this parameter is typically 73used alone, for informational purposes, not during interface configuration). 74.It Fl n Ar 1 \&| 2 75print the IP address of the primary or secondary DNS name server for this 76PPP connection. This is only available if DNS query is enabled, see 77.Ar query-dns . 78.El 79.Pp 80Typically, not both the access concentrator name and the service name are 81specified. 82.Pp 83The 84.Xr ippp 4 85or the 86.Xr pppoe 4 87drivers require a number of additional arguments or optional 88parameters besides the settings that can be adjusted with 89.Xr ifconfig 8 . 90These are things like authentication protocol parameters, but also 91other tunable configuration variables. The 92.Nm 93utility can be used to display the current settings, or adjust these 94parameters as required. 95.Pp 96For whatever intent 97.Nm 98is being called, at least the parameter 99.Ar ifname 100needs to be specified, naming the interface for which the settings 101are to be performed or displayed. Use 102.Xr ifconfig 8 103or 104.Xr netstat 1 105to see which interfaces are available. 106.Pp 107If no other parameter is given, 108.Nm 109will just list the current settings for 110.Ar ifname 111and exit. The reported settings include the current PPP phase the 112interface is in, which can be one of the names 113.Em dead , 114.Em establish , 115.Em authenticate , 116.Em network , 117or 118.Em terminate . 119If an authentication protocol is configured for the interface, the 120name of the protocol to be used, as well as the system name to be used 121or expected will be displayed, plus any possible options to the 122authentication protocol if applicable. Note that the authentication 123secrets (sometimes also called 124.Em keys ) 125are not being returned by the underlying system call, and are thus not 126displayed. 127.Pp 128If any additional parameter is supplied, superuser privileges are 129required, and the command works in 130.Ql set 131mode. This is normally done quietly, unless the option 132.Fl v 133is also enabled, which will cause a final printout of the settings as 134described above once all other actions have been taken. Use of this 135mode will be rejected if the interface is currently in any other phase 136than 137.Em dead . 138Note that you can force an interface into 139.Em dead 140phase by calling 141.Xr ifconfig 8 142with the parameter 143.Ql down . 144.Pp 145The currently supported parameters include: 146.Bl -tag -width xxxxxxxxxxxxxxxxxxxxxxxxx 147.It Ar authproto Ns \&= Ns Em protoname 148Set both his and my authentication protocol to 149.Em protoname . 150The protocol name can be one of 151.Ql chap , 152.Ql pap , 153or 154.Ql none . 155In the latter case, the use of an authentication protocol will be 156turned off for the named interface. This has the side-effect of 157clearing the other authentication-related parameters for this 158interface as well (i. e., system name and authentication secret will 159be forgotten). 160.It Ar myauthproto Ns \&= Ns Em protoname 161Same as above, but only for my end of the link. I. e., this is the 162protocol when remote is authenticator, and I am the peer required to 163authenticate. 164.It Ar hisauthproto Ns \&= Ns Em protoname 165Same as above, but only for his end of the link. 166.It Ar myauthname Ns \&= Ns Em name 167Set my system name for the authentication protocol. 168.It Ar hisauthname Ns \&= Ns Em name 169Set his system name for the authentication protocol. For CHAP, this 170will only be used as a hint, causing a warning message if remote did 171supply a different name. For PAP, it's the name remote must use to 172authenticate himself (in connection with his secret). 173.It Ar myauthsecret Ns \&= Ns Em secret 174Set my secret (key, password) for use in the authentication phase. 175For CHAP, this will be used to compute the response hash value, based 176on remote's challenge. For PAP, it will be transmitted as plaintext 177together with the system name. Don't forget to quote the secrets from 178the shell if they contain shell metacharacters (or whitespace). 179.It Ar myauthkey Ns \&= Ns Em secret 180Same as above. 181.It Ar hisauthsecret Ns \&= Ns Em secret 182Same as above, to be used if we are authenticator and the remote peer 183needs to authenticate. 184.It Ar hisauthkey Ns \&= Ns Em secret 185Same as above. 186.It Ar callin 187Require remote to authenticate himself only when he's calling in, but 188not when we are caller. This is required for some peers that do not 189implement the authentication protocols symmetrically (like Ascend 190routers, for example). 191.It Ar always 192The opposite of 193.Ar callin . 194Require remote to always authenticate, regardless of which side is 195placing the call. This is the default, and will not be explicitly 196displayed in 197.Ql list 198mode. 199.It Ar norechallenge 200Only meaningful with CHAP. Do not re-challenge peer once the initial 201CHAP handshake was successful. Used to work around broken peer 202implementations that can't grok being re-challenged once the 203connection is up. 204.It Ar rechallenge 205With CHAP, send re-challenges at random intervals while the connection 206is in network phase. (The intervals are currently in the range of 300 207through approximately 800 seconds.) This is the default, and will not 208be explicitly displayed in 209.Ql list 210mode. 211.It Ar idle-timeout Ns \&= Ns Em idle-seconds 212For services that are charged by connection time the interface can optionally 213disconnect after a configured idle time. If set to 0, this feature is disabled. 214Note: for ISDN devices, it is preferable to use the 215.Xr isdnd 8 216based timeout mechanism, as isdnd can predict the next charging unit for 217ISDN connections and optimize the timeout with this information. 218.It Ar lcp-timeout Ns \&= Ns Em timeout-value 219Allows to change the value of the LCP timeout. The default value of the LCP 220timeout is currently set to 1 second. The timeout-value must be specified in 221milliseconds. 222.It Ar max-auth-failure Ns \&= Ns Em count 223Since some ISPs disable accounts after too many unsuccessful authentication 224attempts, there is a maximum number of authentication failures before we will 225stop retrying without manual intervention. Manual intervention is either 226changing the authentication data (name, password) or setting the maximum 227retry count. If 228.Em count 229is set to 230.Em 0 231this feature is disabled. 232.It Ar query-dns Ns \&= Ns Em flags 233During PPP protocol negotiation we can query the peer for addresses of two name 234servers. If 235.Ar flags 236is 237.Em 1 238only the first server address will be requested, if 239.Ar flags 240is 241.Em 2 242the second will be requested. Setting 243.Ar flags 244to 245.Em 3 246queries both. 247.Pp 248The result of the negotiation can be retrieved with the 249.Fl n 250option. 251.El 252.Sh EXAMPLES 253.Bd -literal 254# ipppctl ippp0 255ippp0: phase=dead 256 myauthproto=chap myauthname="uriah" 257 hisauthproto=chap hisauthname="ifb-gw" norechallenge 258 lcp timeout: 3.000 s 259.Ed 260.Pp 261Display the settings for ippp0. The interface is currently in 262.Em dead 263phase, i. e. the LCP layer is down, and no traffic is possible. Both 264ends of the connection use the CHAP protocol, my end tells remote the 265system name 266.Ql uriah , 267and remote is expected to authenticate by the name 268.Ql ifb-gw . 269Once the initial CHAP handshake was successful, no further CHAP 270challenges will be transmitted. There are supposedly some known CHAP 271secrets for both ends of the link which are not being shown. 272.Pp 273.Bd -literal 274# ipppctl ippp0 \e 275 authproto=chap \e 276 myauthname=uriah myauthsecret='some secret' \e 277 hisauthname=ifb-gw hisauthsecret='another' \e 278 norechallenge 279.Ed 280.Pp 281A possible call to 282.Nm 283that could have been used to bring the interface into the state shown 284by the previous example. 285.Pp 286The following example is the complete sequence of commands to bring 287a PPPoE connection up: 288.Bd -literal 289# Need ethernet interface UP (or it won't send any packets) 290ifconfig ne0 up 291 292# Let pppoe0 use ne0 as its ethernet interface 293pppoectl -e ne0 pppoe0 294 295# Configure authentication 296pppoectl pppoe0 \\ 297 myauthproto=pap \\ 298 myauthname=XXXXX \\ 299 myauthsecret=YYYYY \\ 300 hisauthproto=none 301 302# Configure the pppoe0 interface itself. These addresses are magic, 303# meaning we don't care about either address and let the remote 304# ppp choose them. 305ifconfig pppoe0 0.0.0.0 0.0.0.1 up 306.Ed 307.Sh SEE ALSO 308.Xr netstat 1 , 309.Xr ippp 4 , 310.Xr pppoe 4 , 311.Xr ifconfig 8 , 312.Xr ifwatchd 8 313.Rs 314.%A B. Lloyd 315.%A W. Simpson 316.%T "PPP Authentication Protocols" 317.%O RFC 1334 318.Re 319.Rs 320.%A W. Simpson, Editor 321.%T "The Point-to-Point Protocol (PPP)" 322.%O RFC 1661 323.Re 324.Rs 325.%A W. Simpson 326.%T "PPP Challenge Handshake Authentication Protocol (CHAP)" 327.%O RFC 1994 328.Re 329.Rs 330.%A L. Mamakos 331.%A K. Lidl 332.%A J. Evarts 333.%A D. Carrel 334.%A D. Simone 335.%A R. Wheeler 336.%T "A Method for Transmitting PPP Over Ethernet (PPPoE)" 337.%O RFC 2516 338.Re 339.Sh HISTORY 340The 341.Nm 342utility is based on the 343.Ic spppcontrol 344utility which appeared in 345.Fx 3.0 . 346.Sh AUTHORS 347The program was written by 348.ie t J\(:org Wunsch, 349.el Joerg Wunsch, 350Dresden, and modified for PPPoE support by Martin Husemann. 351