sbin/spppcontrol/spppcontrol.8

   1 .\" Copyright (C) 1997 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: src/sbin/spppcontrol/spppcontrol.8,v 1.6.2.6 2003/02/23 22:12:39 trhodes Exp $
  26 .\"
  27 .Dd December 30, 2001
  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 DESCRIPTION
  40 The
  41 .Xr sppp 4
  42 driver might require a number of additional arguments or optional
  43 parameters besides the settings that can be adjusted with
  44 .Xr ifconfig 8 .
  45 These are things like authentication protocol parameters, but also
  46 other tunable configuration variables.
  47 The
  48 .Nm
  49 utility can be used to display the current settings, or adjust these
  50 parameters as required.
  51 .Pp
  52 For whatever intent
  53 .Nm
  54 is being called, at least the parameter
  55 .Ar ifname
  56 needs to be specified, naming the interface for which the settings
  57 are to be performed or displayed.
  58 Use
  59 .Xr ifconfig 8 ,
  60 or
  61 .Xr netstat 1
  62 to see which interfaces are available.
  63 .Pp
  64 If no other parameter is given,
  65 .Nm
  66 will just list the current settings for
  67 .Ar ifname
  68 and exit.
  69 The reported settings include the current PPP phase the
  70 interface is in, which can be one of the names
  71 .Em dead ,
  72 .Em establish ,
  73 .Em authenticate ,
  74 .Em network ,
  75 or
  76 .Em terminate .
  77 If an authentication protocol is configured for the interface, the
  78 name of the protocol to be used, as well as the system name to be used
  79 or expected will be displayed, plus any possible options to the
  80 authentication protocol if applicable.
  81 Note that the authentication
  82 secrets (sometimes also called
  83 .Em keys )
  84 are not being returned by the underlying system call, and are thus not
  85 displayed.
  86 .Pp
  87 If any additional parameter is supplied, superuser privileges are
  88 required, and the command works in the
  89 .Dq set
  90 mode.
  91 This is normally done quietly, unless the option
  92 .Fl v
  93 is also enabled, which will cause a final printout of the settings as
  94 described above once all other actions have been taken.
  95 Use of this
  96 mode will be rejected if the interface is currently in any other phase
  97 than
  98 .Em dead .
  99 Note that you can force an interface into
 100 .Em dead
 101 phase by calling
 102 .Xr ifconfig 8
 103 with the parameter
 104 .Cm down .
 105 .Pp
 106 The currently supported parameters include:
 107 .Bl -tag -offset indent -width indent
 108 .It Va authproto Ns Li = Ns Ar protoname
 109 Set both, his and my authentication protocol to
 110 .Ar protoname .
 111 The protocol name can be one of
 112 .Dq Li chap ,
 113 .Dq Li pap ,
 114 or
 115 .Dq Li none .
 116 In the latter case, the use of an authentication protocol will be
 117 turned off for the named interface.
 118 This has the side-effect of
 119 clearing the other authentication-related parameters for this
 120 interface as well (i.e. system name and authentication secret will
 121 be forgotten).
 122 .It Va myauthproto Ns Li = Ns Ar protoname
 123 Same as above, but only for my end of the link.
 124 I.e. this is the
 125 protocol when remote is authenticator, and I am the peer required to
 126 authenticate.
 127 .It Va hisauthproto Ns Li = Ns Ar protoname
 128 Same as above, but only for his end of the link.
 129 .It Va myauthname Ns Li = Ns Ar name
 130 Set my system name for the authentication protocol.
 131 .It Va hisauthname Ns Li = Ns Ar name
 132 Set his system name for the authentication protocol.
 133 For CHAP, this
 134 will only be used as a hint, causing a warning message if remote did
 135 supply a different name.
 136 For PAP, it's the name remote must use to
 137 authenticate himself (in connection with his secret).
 138 .It Va myauthsecret Ns Li = Ns Ar secret
 139 Set my secret (key, password) for use in the authentication phase.
 140 For CHAP, this will be used to compute the response hash value, based
 141 on remote's challenge.
 142 For PAP, it will be transmitted as plain text
 143 together with the system name.
 144 Don't forget to quote the secrets from
 145 the shell if they contain shell metacharacters (or white space).
 146 .It Va myauthkey Ns Li = Ns Ar secret
 147 Same as above.
 148 .It Va hisauthsecret Ns Li = Ns Ar secret
 149 Same as above, to be used if we are an authenticator and the remote peer
 150 needs to authenticate.
 151 .It Va hisauthkey Ns Li = Ns Va secret
 152 Same as above.
 153 .It Va callin
 154 Require remote to authenticate himself only when he's calling in, but
 155 not when we are caller.
 156 This is required for some peers that do not
 157 implement the authentication protocols symmetrically (like Ascend
 158 routers, for example).
 159 .It Va always
 160 The opposite of
 161 .Va callin .
 162 Require remote to always authenticate, regardless of which side is
 163 placing the call.
 164 This is the default, and will not be explicitly
 165 displayed in the
 166 .Dq list
 167 mode.
 168 .It Va norechallenge
 169 Only meaningful with CHAP.
 170 Do not re-challenge peer once the initial
 171 CHAP handshake was successful.
 172 Used to work around broken peer
 173 implementations that can't grok being re-challenged once the
 174 connection is up.
 175 .It Ar rechallenge
 176 With CHAP, send re-challenges at random intervals while the connection
 177 is in network phase.
 178 (The intervals are currently in the range of 300
 179 through approximately 800 seconds.)
 180 This is the default, and will not
 181 be explicitly displayed in the
 182 .Dq list
 183 mode.
 184 .It Va lcp-timeout Ns Li = Ns Ar timeout-value
 185 Allows to change the value of the LCP restart timer.
 186 Values are specified in milliseconds.
 187 The value must be between 10 and 20000 ms,
 188 defaulting to 3000 ms.
 189 .It Va enable-vj
 190 Enable negotiation of Van Jacobsen header compression.
 191 (Enabled by default.)
 192 .It Va disable-vj
 193 Disable negotiation of Van Jacobsen header compression.
 194 .It Va enable-ipv6
 195 Enable negotiation of the IPv6 network control protocol.
 196 (Enabled by default if the kernel has IPv6 enabled.)
 197 .It Va disable-ipv6
 198 Disable negotiation of the IPv6 network control protocol.
 199 Since every IPv4 interface in an IPv6-enabled kernel automatically gets an IPv6
 200 address assigned, this option provides for a way to administratively
 201 prevent the link from attempting to negotiate IPv6.
 202 Note that initialization of an IPv6 interface causes a multicast packet to be
 203 sent, which can cause unwanted traffic costs (for dial-on-demand
 204 interfaces).
 205 .El
 206 .Sh EXAMPLES
 207 .Bd -literal
 208 # spppcontrol bppp0
 209 bppp0:  phase=dead
 210         myauthproto=chap myauthname="uriah"
 211         hisauthproto=chap hisauthname="ifb-gw" norechallenge
 212         lcp-timeout=3000
 213         enable-vj
 214         enable-ipv6
 215 .Ed
 216 .Pp
 217 Display the settings for
 218 .Li bppp0 .
 219 The interface is currently in
 220 .Em dead
 221 phase, i.e. the LCP layer is down, and no traffic is possible.
 222 Both
 223 ends of the connection use the CHAP protocol, my end tells remote the
 224 system name
 225 .Dq Li uriah ,
 226 and remote is expected to authenticate by the name
 227 .Dq Li ifb-gw .
 228 Once the initial CHAP handshake was successful, no further CHAP
 229 challenges will be transmitted.
 230 There are supposedly some known CHAP
 231 secrets for both ends of the link which are not being shown.
 232 .Bd -literal
 233 # spppcontrol bppp0 \e
 234         authproto=chap \e
 235         myauthname=uriah myauthsecret='some secret' \e
 236         hisauthname=ifb-gw hisauthsecret='another' \e
 237         norechallenge
 238 .Ed
 239 .Pp
 240 A possible call to
 241 .Nm
 242 that could have been used to bring the interface into the state shown
 243 by the previous example.
 244 .Sh SEE ALSO
 245 .Xr netstat 1 ,
 246 .Xr sppp 4 ,
 247 .Xr ifconfig 8
 248 .Rs
 249 .%A B. Lloyd
 250 .%A W. Simpson
 251 .%T "PPP Authentication Protocols"
 252 .%O RFC 1334
 253 .Re
 254 .Rs
 255 .%A W. Simpson, Editor
 256 .%T "The Point-to-Point Protocol (PPP)"
 257 .%O RFC 1661
 258 .Re
 259 .Rs
 260 .%A W. Simpson
 261 .%T "PPP Challenge Handshake Authentication Protocol (CHAP)"
 262 .%O RFC 1994
 263 .Re
 264 .Sh HISTORY
 265 The
 266 .Nm
 267 utility appeared in
 268 .Fx 3.0 .
 269 .Sh AUTHORS
 270 The program was written by
 271 .An J\(:org Wunsch ,
 272 Dresden.