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