410 lines
12 KiB
Groff
410 lines
12 KiB
Groff
.\" $NetBSD: pppoectl.8,v 1.30 2016/09/12 05:35:20 sevan Exp $
|
|
.\"
|
|
.\" Copyright (C) 1997 by Joerg Wunsch, Dresden
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) ``AS IS'' AND ANY EXPRESS
|
|
.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
|
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
.\" DISCLAIMED. IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT,
|
|
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
|
.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
|
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
|
|
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
|
|
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
.\" POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.\" From: spppcontrol.1,v 1.1.1.1 1997/10/11 11:30:30 joerg Exp
|
|
.\"
|
|
.\" $Id: pppoectl.8,v 1.30 2016/09/12 05:35:20 sevan Exp $
|
|
.\"
|
|
.\" last edit-date: [Thu Aug 31 10:47:33 2000]
|
|
.\"
|
|
.Dd September 12, 2016
|
|
.Dt PPPOECTL 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm pppoectl ,
|
|
.Nm ipppctl
|
|
.Nd "display or set parameters for an pppoe or isdn ppp (ippp) interface"
|
|
.Sh SYNOPSIS
|
|
.Nm pppoectl
|
|
.Op Fl v
|
|
.Ar ifname
|
|
.Op Ar parameter Ns Op \&= Ns Ar value
|
|
.Op Ar ...
|
|
.Pp
|
|
.Nm ipppctl
|
|
.Op Fl v
|
|
.Ar ifname
|
|
.Op Ar parameter Ns Op \&= Ns Ar value
|
|
.Op Ar ...
|
|
.Pp
|
|
.Nm pppoectl
|
|
.Fl e Ar ethernet-ifname
|
|
.Op Fl s Ar service-name
|
|
.Op Fl a Ar access-concentrator-name
|
|
.Op Fl d
|
|
.Op Fl n Ar 1 \&| 2
|
|
.Ar ifname
|
|
.Pp
|
|
.Nm pppoectl
|
|
.Fl f Ar config-file
|
|
.Ar ifname
|
|
.Op Ar ...
|
|
.Sh DESCRIPTION
|
|
There are two basic modes of operation: configuring security-related
|
|
parameters and attaching a PPPoE interface to its ethernet interface,
|
|
optionally passing in additional parameters for the PPPoE encapsulation.
|
|
.Pp
|
|
The latter usage is indicated by the presence of the
|
|
.Fl e
|
|
option, which takes the name of the ethernet interface as its argument.
|
|
.Pp
|
|
.Bl -tag -width indent
|
|
.It Fl e
|
|
specifies the ethernet interface used to communicate with the
|
|
access concentrator (typically via a DSL modem).
|
|
.It Fl a
|
|
specifies the name of the access concentrator.
|
|
.It Fl s
|
|
specifies the name of the service connected to.
|
|
.It Fl d
|
|
dump the current connection state information (this parameter is typically
|
|
used alone, for informational purposes, not during interface configuration).
|
|
.It Fl n Ar 1 \&| 2
|
|
print the IP address of the primary or secondary DNS name server for this
|
|
PPP connection.
|
|
This is only available if DNS query is enabled, see
|
|
.Ar query-dns .
|
|
.It Fl f
|
|
parse
|
|
.Ar config-file
|
|
for
|
|
.Ar parameter Ns Op \&= Ns Ar value
|
|
pairs, one per line, as if they had been specified on the command line.
|
|
This allows the password to be not passed as a command line argument.
|
|
Unless escaped by \e, comments starting with # to the end of the current line
|
|
are ignored.
|
|
.El
|
|
.Pp
|
|
Typically, not both the access concentrator name and the service name are
|
|
specified.
|
|
.Pp
|
|
The
|
|
.Xr ippp 4
|
|
or the
|
|
.Xr pppoe 4
|
|
drivers require a number of additional arguments or optional
|
|
parameters besides the settings that can be adjusted with
|
|
.Xr ifconfig 8 .
|
|
These are things like authentication protocol parameters, but also
|
|
other tunable configuration variables.
|
|
The
|
|
.Nm
|
|
utility can be used to display the current settings, or adjust these
|
|
parameters as required.
|
|
.Pp
|
|
For whatever intent
|
|
.Nm
|
|
is being called, at least the parameter
|
|
.Ar ifname
|
|
needs to be specified, naming the interface for which the settings
|
|
are to be performed or displayed.
|
|
Use
|
|
.Xr ifconfig 8
|
|
or
|
|
.Xr netstat 1
|
|
to see which interfaces are available.
|
|
.Pp
|
|
If no other parameter is given,
|
|
.Nm
|
|
will just list the current settings for
|
|
.Ar ifname
|
|
and exit.
|
|
The reported settings include the current PPP phase the
|
|
interface is in, which can be one of the names
|
|
.Em dead ,
|
|
.Em establish ,
|
|
.Em authenticate ,
|
|
.Em network ,
|
|
or
|
|
.Em terminate .
|
|
If an authentication protocol is configured for the interface, the
|
|
name of the protocol to be used, as well as the system name to be used
|
|
or expected will be displayed, plus any possible options to the
|
|
authentication protocol if applicable.
|
|
Note that the authentication
|
|
secrets (sometimes also called
|
|
.Em keys )
|
|
are not being returned by the underlying system call, and are thus not
|
|
displayed.
|
|
.Pp
|
|
If any additional parameter is supplied, superuser privileges are
|
|
required, and the command works in
|
|
.Ql set
|
|
mode.
|
|
This is normally done quietly, unless the option
|
|
.Fl v
|
|
is also enabled, which will cause a final printout of the settings as
|
|
described above once all other actions have been taken.
|
|
Use of this mode will be rejected if the interface is currently in any
|
|
other phase than
|
|
.Em dead .
|
|
Note that you can force an interface into
|
|
.Em dead
|
|
phase by calling
|
|
.Xr ifconfig 8
|
|
with the parameter
|
|
.Ql down .
|
|
.Pp
|
|
The currently supported parameters include:
|
|
.Bl -tag -width xxxxxxxxxxxxxxxxxxxxxxxxx
|
|
.It Ar authproto Ns \&= Ns Em protoname
|
|
Set both his and my authentication protocol to
|
|
.Em protoname .
|
|
The protocol name can be one of
|
|
.Ql chap ,
|
|
.Ql pap ,
|
|
or
|
|
.Ql none .
|
|
In the latter case, the use of an authentication protocol will be
|
|
turned off for the named interface.
|
|
This has the side-effect of
|
|
clearing the other authentication-related parameters for this
|
|
interface as well (i.
|
|
e., system name and authentication secret will
|
|
be forgotten).
|
|
.It Ar myauthproto Ns \&= Ns Em protoname
|
|
Same as above, but only for my end of the link.
|
|
I.e., this is the protocol when remote is authenticator,
|
|
and I am the peer required to authenticate.
|
|
.It Ar hisauthproto Ns \&= Ns Em protoname
|
|
Same as above, but only for his end of the link.
|
|
.It Ar myauthname Ns \&= Ns Em name
|
|
Set my system name for the authentication protocol.
|
|
.It Ar hisauthname Ns \&= Ns Em name
|
|
Set his system name for the authentication protocol.
|
|
For CHAP, this will only be used as a hint, causing
|
|
a warning message if remote did supply a different name.
|
|
For PAP, it's the name remote must use to
|
|
authenticate himself (in connection with his secret).
|
|
.It Ar myauthsecret Ns \&= Ns Em secret
|
|
Set my secret (key, password) for use in the authentication phase.
|
|
For CHAP, this will be used to compute the response hash value, based
|
|
on remote's challenge.
|
|
For PAP, it will be transmitted as plaintext
|
|
together with the system name.
|
|
Don't forget to quote the secrets from
|
|
the shell if they contain shell metacharacters (or whitespace).
|
|
.It Ar myauthkey Ns \&= Ns Em secret
|
|
Same as above.
|
|
.It Ar hisauthsecret Ns \&= Ns Em secret
|
|
Same as above, to be used if we are authenticator and the remote peer
|
|
needs to authenticate.
|
|
.It Ar hisauthkey Ns \&= Ns Em secret
|
|
Same as above.
|
|
.It Ar callin
|
|
Require remote to authenticate himself only when he's calling in, but
|
|
not when we are caller.
|
|
This is required for some peers that do not
|
|
implement the authentication protocols symmetrically (like Ascend
|
|
routers, for example).
|
|
.It Ar always
|
|
The opposite of
|
|
.Ar callin .
|
|
Require remote to always authenticate, regardless of which side is
|
|
placing the call.
|
|
This is the default, and will not be explicitly displayed in
|
|
.Ql list
|
|
mode.
|
|
.It Ar norechallenge
|
|
Only meaningful with CHAP.
|
|
Do not re-challenge peer once the initial
|
|
CHAP handshake was successful.
|
|
Used to work around broken peer implementations that can't grok
|
|
being re-challenged once the connection is up.
|
|
.It Ar rechallenge
|
|
With CHAP, send re-challenges at random intervals while the connection
|
|
is in network phase.
|
|
(The intervals are currently in the range of 300
|
|
through approximately 800 seconds.)
|
|
This is the default, and will not be explicitly displayed in
|
|
.Ql list
|
|
mode.
|
|
.It Ar idle-timeout Ns \&= Ns Em idle-seconds
|
|
For services that are charged by connection time the interface can optionally
|
|
disconnect after a configured idle time.
|
|
If set to 0, this feature is disabled.
|
|
Note: for ISDN devices, it is preferable to use the
|
|
.Xr isdnd 8
|
|
based timeout mechanism, as isdnd can predict the next charging unit for
|
|
ISDN connections and optimize the timeout with this information.
|
|
.It Ar lcp-timeout Ns \&= Ns Em timeout-value
|
|
Allows to change the value of the LCP timeout.
|
|
The default value of the LCP timeout is currently set to 1 second.
|
|
The timeout-value must be specified in milliseconds.
|
|
.It Ar max-noreceive Ns \&= Ns Em sec
|
|
Sets the number of seconds after last reception of data from the peer before
|
|
the line state is probed by sending LCP echo requests.
|
|
The
|
|
.Em sec
|
|
interval is not used verbatim, the first echo request might be delayed upto
|
|
10 seconds after the configured interval.
|
|
.It Ar max-alive-missed Ns \&= Ns Em count
|
|
Sets the number of unanswered LCP echo requests that we will tolerate before
|
|
considering a connection to be dead.
|
|
LCP echo requests are sent in 10 seconds interval after the configured
|
|
.Em max-noreceive
|
|
interval has passed with no data received from the peer.
|
|
.It Ar max-auth-failure Ns \&= Ns Em count
|
|
Since some ISPs disable accounts after too many unsuccessful authentication
|
|
attempts, there is a maximum number of authentication failures before we will
|
|
stop retrying without manual intervention.
|
|
Manual intervention is either changing the authentication data
|
|
(name, password) or setting the maximum retry count.
|
|
If
|
|
.Em count
|
|
is set to
|
|
.Em 0
|
|
this feature is disabled.
|
|
.It Ar clear-auth-failure
|
|
If an authentication failure has been caused by remote problems and you want
|
|
to retry connecting using unchanged local settings, this command can be used
|
|
to reset the failure count to zero.
|
|
.It Ar query-dns Ns \&= Ns Em flags
|
|
During PPP protocol negotiation we can query the peer
|
|
for addresses of two name servers.
|
|
If
|
|
.Ar flags
|
|
is
|
|
.Em 1
|
|
only the first server address will be requested, if
|
|
.Ar flags
|
|
is
|
|
.Em 2
|
|
the second will be requested.
|
|
Setting
|
|
.Ar flags
|
|
to
|
|
.Em 3
|
|
queries both.
|
|
.Pp
|
|
The result of the negotiation can be retrieved with the
|
|
.Fl n
|
|
option.
|
|
.El
|
|
.Sh EXAMPLES
|
|
.Bd -literal
|
|
# ipppctl ippp0
|
|
ippp0: phase=dead
|
|
myauthproto=chap myauthname="uriah"
|
|
hisauthproto=chap hisauthname="ifb-gw" norechallenge
|
|
lcp timeout: 3.000 s
|
|
.Ed
|
|
.Pp
|
|
Display the settings for ippp0.
|
|
The interface is currently in
|
|
.Em dead
|
|
phase, i.e. the LCP layer is down, and no traffic is possible.
|
|
Both ends of the connection use the CHAP protocol,
|
|
my end tells remote the system name
|
|
.Ql uriah ,
|
|
and remote is expected to authenticate by the name
|
|
.Ql ifb-gw .
|
|
Once the initial CHAP handshake was successful, no further CHAP
|
|
challenges will be transmitted.
|
|
There are supposedly some known CHAP
|
|
secrets for both ends of the link which are not being shown.
|
|
.Pp
|
|
.Bd -literal
|
|
# ipppctl ippp0 \e
|
|
authproto=chap \e
|
|
myauthname=uriah myauthsecret='some secret' \e
|
|
hisauthname=ifb-gw hisauthsecret='another' \e
|
|
norechallenge
|
|
.Ed
|
|
.Pp
|
|
A possible call to
|
|
.Nm
|
|
that could have been used to bring the interface into the state shown
|
|
by the previous example.
|
|
.Pp
|
|
The following example is the complete sequence of commands to bring
|
|
a PPPoE connection up:
|
|
.Bd -literal
|
|
# Need ethernet interface UP (or it won't send any packets)
|
|
ifconfig ne0 up
|
|
|
|
# Let pppoe0 use ne0 as its ethernet interface
|
|
pppoectl -e ne0 pppoe0
|
|
|
|
# Configure authentication
|
|
pppoectl pppoe0 \e
|
|
myauthproto=pap \e
|
|
myauthname=XXXXX \e
|
|
myauthsecret=YYYYY \e
|
|
hisauthproto=none
|
|
|
|
# Configure the pppoe0 interface itself. These addresses are magic,
|
|
# meaning we don't care about either address and let the remote
|
|
# ppp choose them.
|
|
ifconfig pppoe0 0.0.0.0 0.0.0.1 netmask 0xffffffff up
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr netstat 1 ,
|
|
.Xr ippp 4 ,
|
|
.Xr pppoe 4 ,
|
|
.Xr ifconfig 8 ,
|
|
.Xr ifwatchd 8
|
|
.Rs
|
|
.%A B. Lloyd
|
|
.%A W. Simpson
|
|
.%T "PPP Authentication Protocols"
|
|
.%O RFC 1334
|
|
.Re
|
|
.Rs
|
|
.%A W. Simpson, Editor
|
|
.%T "The Point-to-Point Protocol (PPP)"
|
|
.%O RFC 1661
|
|
.Re
|
|
.Rs
|
|
.%A W. Simpson
|
|
.%T "PPP Challenge Handshake Authentication Protocol (CHAP)"
|
|
.%O RFC 1994
|
|
.Re
|
|
.Rs
|
|
.%A L. Mamakos
|
|
.%A K. Lidl
|
|
.%A J. Evarts
|
|
.%A D. Carrel
|
|
.%A D. Simone
|
|
.%A R. Wheeler
|
|
.%T "A Method for Transmitting PPP Over Ethernet (PPPoE)"
|
|
.%O RFC 2516
|
|
.Re
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
utility is based on the
|
|
.Ic spppcontrol
|
|
utility which appeared in
|
|
.Fx 3.0 .
|
|
The
|
|
.Nm
|
|
utility first appeared in
|
|
.Nx 1.6 .
|
|
.Sh AUTHORS
|
|
The program was written by J\(:org Wunsch, Dresden,
|
|
and modified for PPPoE support by Martin Husemann.
|