GC !__DragonFly__ section.
[dragonfly.git] / 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.