`pppoectl`

Display or set parameters for a PPPOE interface

Syntax:

pppoectl [-v] ifname [parameter[=value]] [...]
pppoectl -e ethernet-ifname [-s service-name]
         [-a access-concentrator-name] [-d] [-n 1 | 2] ifname
pppoectl -f config-file ifname [...]

Options:

-e ethernet-ifname: The Ethernet interface to use to communicate with the access concentrator (typically via a DSL modem).
-a access-concentrator-name: The name of the access concentrator.
-s service-name: The name of the service connected to.
-d: Dump the current connection state information. You typically use this parameter alone, for informational purposes, not when configuring an interface.
-n 1 | 2: Print the IP address of the primary or secondary DNS name server for this PPP connection. This is available only if DNS query is enabled; see the query-dns parameter.
-f config-file: Parse config-file, ignoring lines starting with a #, for parameter[=value] pairs, one per line, as if they had been specified on the command line. This lets you avoid passing the password as a command-line argument.

Description:

The pppoectl utility displays or sets parameters for a pppoe interface. There are two basic modes of operation:

configuring security-related parameters
attaching a PPPOE interface to its Ethernet interface, optionally passing in additional parameters for the PPPOE encapsulation

The latter usage is indicated by the presence of the -e option, which takes the name of the Ethernet interface as its argument. You don't typically specify both the access concentrator name and the service name.

PPPOE drivers require a number of additional arguments or optional parameters besides the settings that you can adjust with ifconfig. These are things such as authentication protocol parameters, but also other tunable configuration variables. You can use pppoectl to display the current settings or adjust these parameters as required.

You always need to specify the ifname argument, in order to identify the interface for which to set or display the parameters. Use ifconfig or netstat to see which interfaces are available.

If no other parameter is given, pppoectl just lists the current settings for ifname, and then exits. The reported settings include the current PPP phase the interface is in, which can be one of dead, establish, authenticate, network, or 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 are displayed, plus any possible options to the authentication protocol if applicable. Note that the authentication secrets (sometimes also called keys) aren't returned by the underlying system call, and thus aren't displayed.

If any additional parameter is supplied, superuser privileges are required, and the command works in “set” mode. This is normally done quietly, unless you specify the -v option, which causes a final printout of the settings as described above once all other actions have been taken. Use of this mode is rejected if the interface is currently in any other phase than dead. Note that you can force an interface into the dead phase by calling ifconfig with the parameter down.

Supported parameters

The currently supported parameters include:

authproto=protoname

Set both his and my authentication protocol to protoname. The protocol name can be one of chap, pap, or none. In the latter case, the use of an authentication protocol is 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. the system name and authentication secret will be forgotten).

myauthproto=protoname

Same as authproto, but only for my end of the link. In other words, this is the protocol when the remote is the authenticator, and I am the peer required to authenticate.

hisauthproto=protoname

The same as authproto, but only for his end of the link.

myauthname=name

Set my system name for the authentication protocol.

hisauthname=name

Set his system name for the authentication protocol. For CHAP, this is used only as a hint, causing a warning message if the remote supplied a different name. For PAP, it's the name remote must use to authenticate itself (in connection with its secret).

myauthsecret=secret

Set my secret (key, password) for use in the authentication phase. For CHAP, this is used to compute the response hash value, based on remote's challenge. For PAP, it's transmitted as plain text together with the system name. Don't forget to quote the secrets from the shell if they contain shell metacharacters (or white space).

myauthkey=secret

The same as myauthsecret.

hisauthsecret=secret

Similar to myauthsecret, to be used if we are the authenticator, and the remote peer needs to authenticate.

hisauthkey=secret

The same as hisauthsecret.

callin

Require the remote to authenticate itself only when it's calling in, but not when we're the caller. This is required for some peers that don't implement the authentication protocols symmetrically (such as Ascend routers, for example).

always

The opposite of callin. Require the remote to always authenticate, regardless of which side is placing the call. This is the default, and isn't explicitly displayed in list mode.

norechallenge

Meaningful only with CHAP. Don't rechallenge a peer once the initial CHAP handshake was successful. Use this to work around broken peer implementations that can't handle being rechallenged once the connection is up.

rechallenge

With CHAP, send rechallenges 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 isn't explicitly displayed in list mode.

idle-timeout=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.

For ISDN devices, it's preferable to use the isdnd-based timeout mechanism, as isdnd can predict the next charging unit for ISDN connections and optimize the timeout with this information.

lcp-timeout=timeout-value

Change the value of the LCP timeout. The default value of the LCP timeout is currently 1 second. Specify the timeout-value in milliseconds.

max-noreceive=sec

Set the number of seconds after the last reception of data from the peer before the line state is probed by sending LCP echo requests. The sec interval isn't used verbatim; the first echo request might be delayed up to 10 seconds after the configured interval.

max-alive-missed=count

Set the number of unanswered LCP echo requests to tolerate before considering a connection to be dead. LCP echo requests are sent in 10-second intervals after the configured max-noreceive interval has passed with no data received from the peer.

max-auth-failure=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 count is set to 0, this feature is disabled.

clear-auth-failure

If an authentication failure has been caused by remote problems, and you want to retry connecting using unchanged local settings, you can use this command to reset the failure count to zero.

query-dns=flags

During PPP protocol negotiation, we can query the peer for addresses of two name servers. If flags is 1, only the first server address is requested; if flags is 2, the second is requested. Setting flags to 3 queries both.

You can retrieve the result of the negotiation with the -n option.

Examples:

The following example is the complete sequence of commands to bring a PPPOE connection up:

# Need ethernet interface UP (or it won't send any packets)
ifconfig ne0 up

# Create the PPPOE interface
ifconfig pppoe0 create

# Let pppoe0 use ne0 as its ethernet interface
pppoectl -e ne0 pppoe0

# Configure authentication
pppoectl pppoe0 myauthproto=pap myauthname=XXXXX \
myauthsecret=YYYYY  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

In order to be configured as a PPPOE server, you should set the pppoe interface to use link0 mode, so that it can wait for incoming PPPOE session requests. For example, the following makes the interface wait for requests coming from the en0 interface:

ifconfig pppoe0 create # create an PPPOE interface
ifconfig pppoe0 link0  # set mode as link0
pppoectl -e en0 pppoe0 # link it with en0 ethernet interface
pppoectl  pppoe0 hisauthproto=pap hisauthname=XXX hisauthsecret=YYY
                       # configure authentication
ifconfig pppoe0 inet ip_address_self ip_address_client
                       # assign ip addresses
ifconfig en0 up        # up en0 to receive incoming data.

Files:

/dev/io-net/ppp_en: The default PPPOE device.
/etc/ppp/pppoe-down: The default downscript.
/etc/ppp/pppoe-up: The default upscript.