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 [...]

Runs on:

QNX Neutrino

Options:

-a access-concentrator-name: The name of the access concentrator.
-d: Dump the current connection state information. You typically use this parameter alone, for informational purposes, not when configuring an interface.
-e ethernet-ifname: The Ethernet interface to use to communicate with the access concentrator (typically via a DSL modem).
-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.
-s service-name: The name of the service connected to.
-v[v...]: Be verbose. Specifying additional -v options increases verbosity.

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.
Note: 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.

Note: If you find the PPPoE has problems connecting to certain sites on the Internet, see the technote PPPOE and Path MTU Discovery.

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.