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