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