1.\" Copyright (C) 1997, 2001 by Joerg Wunsch, Dresden 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) ``AS IS'' AND ANY EXPRESS 14.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 15.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 16.\" DISCLAIMED. IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT, 17.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 18.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 19.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 21.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 22.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 23.\" POSSIBILITY OF SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd October 22, 2021 28.Dt SPPPCONTROL 8 29.Os 30.Sh NAME 31.Nm spppcontrol 32.Nd display or set parameters for an sppp interface 33.Sh SYNOPSIS 34.Nm 35.Op Fl v 36.Ar ifname 37.Op Ar parameter Ns Op Li = Ns Ar value 38.Op Ar ... 39.Sh DEPRECATION NOTICE 40The 41.Xr sppp 4 42module and the 43.Nm 44utility is not present in 45.Fx 14.0 46and later. 47.Sh DESCRIPTION 48The 49.Xr sppp 4 50driver might require a number of additional arguments or optional 51parameters besides the settings that can be adjusted with 52.Xr ifconfig 8 . 53These are things like authentication protocol parameters, but also 54other tunable configuration variables. 55The 56.Nm 57utility can be used to display the current settings, or adjust these 58parameters as required. 59.Pp 60For whatever intent 61.Nm 62is being called, at least the parameter 63.Ar ifname 64needs to be specified, naming the interface for which the settings 65are to be performed or displayed. 66Use 67.Xr ifconfig 8 , 68or 69.Xr netstat 1 70to see which interfaces are available. 71.Pp 72If no other parameter is given, 73.Nm 74will just list the current settings for 75.Ar ifname 76and exit. 77The reported settings include the current PPP phase the 78interface is in, which can be one of the names 79.Em dead , 80.Em establish , 81.Em authenticate , 82.Em network , 83or 84.Em terminate . 85If an authentication protocol is configured for the interface, the 86name of the protocol to be used, as well as the system name to be used 87or expected will be displayed, plus any possible options to the 88authentication protocol if applicable. 89Note that the authentication 90secrets (sometimes also called 91.Em keys ) 92are not being returned by the underlying system call, and are thus not 93displayed. 94.Pp 95If any additional parameter is supplied, superuser privileges are 96required, and the command works in the 97.Dq set 98mode. 99This is normally done quietly, unless the option 100.Fl v 101is also enabled, which will cause a final printout of the settings as 102described above once all other actions have been taken. 103Use of this 104mode will be rejected if the interface is currently in any other phase 105than 106.Em dead . 107Note that you can force an interface into 108.Em dead 109phase by calling 110.Xr ifconfig 8 111with the parameter 112.Cm down . 113.Pp 114The currently supported parameters include: 115.Bl -tag -offset indent -width indent 116.It Va authproto Ns Li = Ns Ar protoname 117Set both, his and my authentication protocol to 118.Ar protoname . 119The protocol name can be one of 120.Dq Li chap , 121.Dq Li pap , 122or 123.Dq Li none . 124In the latter case, the use of an authentication protocol will be 125turned off for the named interface. 126This has the side-effect of 127clearing the other authentication-related parameters for this 128interface as well (i.e., system name and authentication secret will 129be forgotten). 130.It Va myauthproto Ns Li = Ns Ar protoname 131Same as above, but only for my end of the link. 132I.e., this is the 133protocol when remote is authenticator, and I am the peer required to 134authenticate. 135.It Va hisauthproto Ns Li = Ns Ar protoname 136Same as above, but only for his end of the link. 137.It Va myauthname Ns Li = Ns Ar name 138Set my system name for the authentication protocol. 139.It Va hisauthname Ns Li = Ns Ar name 140Set his system name for the authentication protocol. 141For CHAP, this 142will only be used as a hint, causing a warning message if remote did 143supply a different name. 144For PAP, it is the name remote must use to 145authenticate himself (in connection with his secret). 146.It Va myauthsecret Ns Li = Ns Ar secret 147Set my secret (key, password) for use in the authentication phase. 148For CHAP, this will be used to compute the response hash value, based 149on remote's challenge. 150For PAP, it will be transmitted as plain text 151together with the system name. 152Do not forget to quote the secrets from 153the shell if they contain shell metacharacters (or white space). 154.It Va myauthkey Ns Li = Ns Ar secret 155Same as above. 156.It Va hisauthsecret Ns Li = Ns Ar secret 157Same as above, to be used if we are an authenticator and the remote peer 158needs to authenticate. 159.It Va hisauthkey Ns Li = Ns Va secret 160Same as above. 161.It Va callin 162Require remote to authenticate himself only when he is calling in, but 163not when we are caller. 164This is required for some peers that do not 165implement the authentication protocols symmetrically (like Ascend 166routers, for example). 167.It Va always 168The opposite of 169.Va callin . 170Require remote to always authenticate, regardless of which side is 171placing the call. 172This is the default, and will not be explicitly 173displayed in the 174.Dq list 175mode. 176.It Va norechallenge 177Only meaningful with CHAP. 178Do not re-challenge peer once the initial 179CHAP handshake was successful. 180Used to work around broken peer 181implementations that cannot grok being re-challenged once the 182connection is up. 183.It Ar rechallenge 184With CHAP, send re-challenges at random intervals while the connection 185is in network phase. 186(The intervals are currently in the range of 300 187through approximately 800 seconds.) 188This is the default, and will not 189be explicitly displayed in the 190.Dq list 191mode. 192.It Va lcp-timeout Ns Li = Ns Ar timeout-value 193Allows to change the value of the LCP restart timer. 194Values are 195specified in milliseconds. 196The value must be between 10 and 20000 ms, 197defaulting to 3000 ms. 198.It Va enable-vj 199Enable negotiation of Van Jacobsen header compression. 200(Enabled by default.) 201.It Va disable-vj 202Disable negotiation of Van Jacobsen header compression. 203.It Va enable-ipv6 204Enable negotiation of the IPv6 network control protocol. 205(Enabled by default if the kernel has IPv6 enabled.) 206.It Va disable-ipv6 207Disable negotiation of the IPv6 network control protocol. 208Since every 209IPv4 interface in an IPv6-enabled kernel automatically gets an IPv6 210address assigned, this option provides for a way to administratively 211prevent the link from attempting to negotiate IPv6. 212Note that 213initialization of an IPv6 interface causes a multicast packet to be 214sent, which can cause unwanted traffic costs (for dial-on-demand 215interfaces). 216.El 217.Sh EXAMPLES 218.Bd -literal 219# spppcontrol bppp0 220bppp0: phase=dead 221 myauthproto=chap myauthname="uriah" 222 hisauthproto=chap hisauthname="ifb-gw" norechallenge 223 lcp-timeout=3000 224 enable-vj 225 enable-ipv6 226.Ed 227.Pp 228Display the settings for 229.Li bppp0 . 230The interface is currently in 231.Em dead 232phase, i.e., the LCP layer is down, and no traffic is possible. 233Both 234ends of the connection use the CHAP protocol, my end tells remote the 235system name 236.Dq Li uriah , 237and remote is expected to authenticate by the name 238.Dq Li ifb-gw . 239Once the initial CHAP handshake was successful, no further CHAP 240challenges will be transmitted. 241There are supposedly some known CHAP 242secrets for both ends of the link which are not being shown. 243.Bd -literal 244# spppcontrol bppp0 \e 245 authproto=chap \e 246 myauthname=uriah myauthsecret='some secret' \e 247 hisauthname=ifb-gw hisauthsecret='another' \e 248 norechallenge 249.Ed 250.Pp 251A possible call to 252.Nm 253that could have been used to bring the interface into the state shown 254by the previous example. 255.Sh SEE ALSO 256.Xr netstat 1 , 257.Xr sppp 4 , 258.Xr ifconfig 8 259.Rs 260.%A B. Lloyd 261.%A W. Simpson 262.%T "PPP Authentication Protocols" 263.%O RFC 1334 264.Re 265.Rs 266.%A W. Simpson, Editor 267.%T "The Point-to-Point Protocol (PPP)" 268.%O RFC 1661 269.Re 270.Rs 271.%A W. Simpson 272.%T "PPP Challenge Handshake Authentication Protocol (CHAP)" 273.%O RFC 1994 274.Re 275.Sh HISTORY 276The 277.Nm 278utility appeared in 279.Fx 3.0 . 280.Sh AUTHORS 281The program was written by 282.An J\(:org Wunsch , 283Dresden. 284