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