pppLib

NAME

pppLib - Point-to-Point Protocol library

ROUTINES

pppInit( ) - initialize a PPP network interface
pppDelete( ) - delete a PPP network interface

DESCRIPTION

This library implements the VxWorks Point-to-Point Protocol (PPP) facility. PPP allows VxWorks to communicate with other machines by sending encapsulated multi-protocol datagrams over a point-to-point serial link. VxWorks may have up to 16 PPP interfaces active at any one time. Each individual interface (or "unit") operates independent of the state of other PPP units.

USER-CALLABLE ROUTINES

PPP network interfaces are initialized using the pppInit( ) routine. This routine's parameters specify the unit number, the name of the serial interface (tty) device, Internet (IP) addresses for both ends of the link, the interface baud rate, an optional pointer to a configuration options structure, and an optional pointer to a configuration options file. The pppDelete( ) routine deletes a specified PPP interface.

DATA ENCAPSULATION

PPP uses HDLC-like framing, in which five header and three trailer octets are used to encapsulate each datagram. In environments where bandwidth is at a premium, the total encapsulation may be shortened to four octets with the available address/control and protocol field compression options.

LINK CONTROL PROTOCOL

PPP incorporates a link-layer protocol called Link Control Protocol (LCP), which is responsible for the link set up, configuration, and termination. LCP provides for automatic negotiation of several link options, including datagram encapsulation format, user authentication, and link monitoring (LCP echo request/reply).

NETWORK CONTROL PROTOCOLS

PPP's Network Control Protocols (NCP) allow PPP to support different network protocols. VxWorks supports only one NCP, the Internet Protocol Control Protocol (IPCP), which allows the establishment and configuration of IP over PPP links. IPCP supports the negotiation of IP addresses and TCP/IP header compression (commonly called "VJ" compression).

AUTHENTICATION

The VxWorks PPP implementation supports two separate user authentication protocols: the Password Authentication Protocol (PAP) and the Challenge-Handshake Authentication Protocol (CHAP). While PAP only authenticates at the time of link establishment, CHAP may be configured to periodically require authentication throughout the life of the link. Both protocols are independent of one another, and either may be configured in through the PPP options structure or options file.

IMPLEMENTATION

Each VxWorks PPP interface is handled by two tasks: the daemon task (tPPPunit) and the write task (tPPPunitWrt).
The daemon task controls the various PPP control protocols (LCP, IPCP, CHAP, and PAP). Each PPP interface has its own daemon task that handles link set up, negotiation of link options, link-layer user athentication, and link termination. The daemon task is not used for the actual sending and receiving of IP datagrams.
The write task controls the transmit end of a PPP driver interface. Each PPP interface has its own write task that handles the actual sending of a packet by writing data to the tty device. Whenever a packet is ready to be sent out, the PPP driver activates this task by giving a semaphore. The write task then completes the packet framing and writes the packet data to the tty device.
The receive end of the PPP interface is implemented as a "hook" into the tty device driver. The tty driver's receive interrupt service routine (ISR) calls the PPP driver's ISR every time a character is received on the serial channel. When the correct PPP framing character sequence is received, the PPP ISR schedules the tNetTask task to call the PPP input routine. The PPP input routine reads a whole PPP packet out of the tty ring buffer and processes it according to PPP framing rules. The packet is then queued either to the IP input queue or to the PPP daemon task input queue.

INCLUDE FILES

pppLib.h

ACKNOWLEDGEMENT

This program is based on original work done by Paul Mackerras of Australian National University, Brad Parker, Greg Christy, Drew D. Perkins, Rick Adams, and Chris Torek.

Libraries : Routines

pppInit( )

NAME

pppInit( ) - initialize a PPP network interface

SYNOPSIS

int pppInit
    (
    int           unit,        /* PPP interface unit number to initialize */
    char *        devname,     /* name of the tty device to be used */
    char *        local_addr,  /* local IP address of the PPP interface */
    char *        remote_addr, /* remote peer IP address of the PPP link */
    int           baud,        /* baud rate of tty; NULL = default */
    PPP_OPTIONS * pOptions,    /* PPP options structure pointer */
    char *        fOptions     /* PPP options file name */
    )

DESCRIPTION

This routine initializes a Point-to-Point Protocol (PPP) network interface. The parameters to this routine specify the unit number (unit) of the PPP interface, the name of the serial interface (tty) device (devname), the IP addresses of the local and remote ends of the link, the interface baud rate, an optional configuration options structure pointer, and an optional configuration options file name.

IP ADDRESSES

The local_addr and remote_addr parameters specify the IP addresses of the local and remote ends of the PPP link, respectively. If local_addr is NULL, the local IP address will be negotiated with the remote peer. If the remote peer does not assign a local IP address, it will default to the address associated with the local target's machine name. If remote_addr is NULL, the remote peer's IP address will obtained from the remote peer. A routing table entry to the remote peer will be automatically added once the PPP link is established.

CONFIGURATION OPTIONS STRUCTURE

The optional parameter pOptions specifies configuration options for the PPP link. If NULL, this parameter is ignored, otherwise it is assumed to be a pointer to a PPP_OPTIONS options structure (defined in h/netinet/ppp/options.h).
The "flags" member of the PPP_OPTIONS structure is a bit-mask, where the following bit-flags may be specified:

OPT_NO_ALL
Do not request/allow any options.

OPT_PASSIVE_MODE
Set passive mode.

OPT_SILENT_MODE
Set silent mode.

OPT_DEFAULTROUTE
Add default route.

OPT_PROXYARP
Add proxy ARP entry.

OPT_IPCP_ACCEPT_LOCAL
Accept peer's idea of the local IP address.

OPT_IPCP_ACCEPT_REMOTE
Accept peer's idea of the remote IP address.

OPT_NO_IP
Disable IP address negotiation.

OPT_NO_ACC
Disable address/control compression.

OPT_NO_PC
Disable protocol field compression.

OPT_NO_VJ
Disable VJ (Van Jacobson) compression.

OPT_NO_VJCCOMP
Disable VJ (Van Jacobson) connnection ID compression.

OPT_NO_ASYNCMAP
Disable async map negotiation.

OPT_NO_MN
Disable magic number negotiation.

OPT_NO_MRU
Disable MRU (Maximum Receive Unit) negotiation.

OPT_NO_PAP
Do not allow PAP authentication with peer.

OPT_NO_CHAP
Do not allow CHAP authentication with peer.

OPT_REQUIRE_PAP
Require PAP authentication with peer.

OPT_REQUIRE_CHAP
Require CHAP authentication with peer.

OPT_LOGIN
Use the login password database for PAP authentication of peer.

OPT_DEBUG
Enable PPP daemon debug mode.

OPT_DRIVER_DEBUG
Enable PPP driver debug mode.

The remaining members of the PPP_OPTIONS structure specify PPP configurations options that require string values. These options are:

char *asyncmap
Set the desired async map to the specified string.

char *escape_chars
Set the chars to escape on transmission to the specified string.

char *vj_max_slots
Set maximum number of VJ compression header slots to the specified string.

char *netmask
Set netmask value for negotiation to the specified string.

char *mru
Set MRU value for negotiation to the specified string.

char *mtu
Set MTU (Maximum Transmission Unit) value for negotiation to the specified string.

char *lcp_echo_failure
Set the maximum number of consecutive LCP echo failures to the specified string.

char *lcp_echo_interval
Set the interval in seconds between LCP echo requests to the specified string.

char *lcp_restart
Set the timeout in seconds for the LCP negotiation to the specified string.

char *lcp_max_terminate
Set the maximum number of transmissions for LCP termination requests to the specified string.

char *lcp_max_configure
Set the maximum number of transmissions for LCP configuration requests to the specified string.

char *lcp_max_failure
Set the maximum number of LCP configuration NAKs to the specified string.

char *ipcp_restart
Set the timeout in seconds for IPCP negotiation to the specified string.

char *ipcp_max_terminate
Set the maximum number of transmissions for IPCP termination requests to the specified string.

char *ipcp_max_configure
Set the maximum number of transmissions for IPCP configuration requests to the specified string.

char *ipcp_max_failure
Set the maximum number of IPCP configuration NAKs to the specified string.

char *local_auth_name
Set the local name for authentication to the specified string.

char *remote_auth_name
Set the remote name for authentication to the specified string.

char *pap_file
Get PAP secrets from the specified file. This option is necessary if either peer requires PAP authentication.

char *pap_user_name
Set the user name for PAP authentication with the peer to the specified string.

char *pap_passwd
Set the password for PAP authentication with the peer to the specified string.

char *pap_restart
Set the timeout in seconds for PAP negotiation to the specified string.

char *pap_max_authreq
Set the maximum number of transmissions for PAP authentication requests to the specified string.

char *chap_file
Get CHAP secrets from the specified file. This option is necessary if either peer requires CHAP authentication.

char *chap_restart
Set the timeout in seconds for CHAP negotiation to the specified string.

char *chap_interval
Set the interval in seconds for CHAP rechallenge to the specified string.

char *chap_max_challenge
Set the maximum number of transmissions for CHAP challenge to the specified string.

CONFIGURATION OPTIONS FILE

The optional parameter fOptions specifies configuration options for the PPP link. If NULL, this parameter is ignored, otherwise it is assumed to be the name of a configuration options file. The format of the options file is one option per line; comment lines start with "#". The following options are recognized:

no_all
Do not request/allow any options.

passive_mode
Set passive mode.

silent_mode
Set silent mode.

defaultroute
Add default route.

proxyarp
Add proxy ARP entry.

ipcp_accept_local
Accept peer's idea of the local IP address.

ipcp_accept_remote
Accept peer's idea of the remote IP address.

no_ip
Disable IP address negotiation.

no_acc
Disable address/control compression.

no_pc
Disable protocol field compression.

no_vj
Disable VJ (Van Jacobson) compression.

no_vjccomp
Disable VJ (Van Jacobson) connnection ID compression.

no_asyncmap
Disable async map negotiation.

no_mn
Disable magic number negotiation.

no_mru
Disable MRU (Maximum Receive Unit) negotiation.

no_pap
Do not allow PAP authentication with peer.

no_chap
Do not allow CHAP authentication with peer.

require_pap
Require PAP authentication with peer.

require_chap
Require CHAP authentication with peer.

login
Use the login password database for PAP authentication of peer.

debug
Enable PPP daemon debug mode.

driver_debug
Enable PPP driver debug mode.

asyncmap value
Set the desired async map to the specified value.

escape_chars value
Set the chars to escape on transmission to the specified value.

vj_max_slots value
Set maximum number of VJ compression header slots to the specified value.

netmask value
Set netmask value for negotiation to the specified value.

mru value
Set MRU value for negotiation to the specified value.

mtu value
Set MTU value for negotiation to the specified value.

lcp_echo_failure value
Set the maximum consecutive LCP echo failures to the specified value.

lcp_echo_interval value
Set the interval in seconds between LCP echo requests to the specified value.

lcp_restart value
Set the timeout in seconds for the LCP negotiation to the specified value.

lcp_max_terminate value
Set the maximum number of transmissions for LCP termination requests to the specified value.

lcp_max_configure value
Set the maximum number of transmissions for LCP configuration requests to the specified value.

lcp_max_failure value
Set the maximum number of LCP configuration NAKs to the specified value.

ipcp_restart value
Set the timeout in seconds for IPCP negotiation to the specified value.

ipcp_max_terminate value
Set the maximum number of transmissions for IPCP termination requests to the specified value.

ipcp_max_configure value
Set the maximum number of transmissions for IPCP configuration requests to the specified value.

ipcp_max_failure value
Set the maximum number of IPCP configuration NAKs to the specified value.

local_auth_name name
Set the local name for authentication to the specified name.

remote_auth_name name
Set the remote name for authentication to the specified name.

pap_file file
Get PAP secrets from the specified file. This option is necessary if either peer requires PAP authentication.

pap_user_name name
Set the user name for PAP authentication with the peer to the specified name.

-
Set the password for PAP authentication with the peer to the specified password.

pap_restart value
Set the timeout in seconds for PAP negotiation to the specified value.

pap_max_authreq value
Set the maximum number of transmissions for PAP authentication requests to the specified value.

chap_file file
Get CHAP secrets from the specified file. This option is necessary if either peer requires CHAP authentication.

chap_restart value
Set the timeout in seconds for CHAP negotiation to the specified value.

chap_interval value
Set the interval in seconds for CHAP rechallenge to the specified value.

chap_max_challenge value
Set the maximum number of transmissions for CHAP challenge to the specified value.

AUTHENTICATION

The VxWorks PPP implementation supports two separate user authentication protocols: the Password Authentication Protocol (PAP) and the Challenge-Handshake Authentication Protocol (CHAP). If authentication is required by either peer, it must be satisfactorily completed before the PPP link becomes fully operational. If authentication fails, the link will be automatically terminated.

EXAMPLES

The following routine initializes a PPP interface that uses the target's second serial port (/tyCo/1). The local IP address is 90.0.0.1; the IP address of the remote peer is 90.0.0.10. The baud rate is the default rate for the tty device. VJ compression and authentication have been disabled, and LCP echo requests have been enabled.
PPP_OPTIONS pppOpt;   /* PPP configuration options */

void routine ()
    {
    pppOpt.flags = OPT_PASSIVE_MODE | OPT_NO_PAP | OPT_NO_CHAP | OPT_NO_VJ;
    pppOpt.lcp_echo_interval = "30";
    pppOpt.lcp_echo_failure = "10";

    pppInit (0, "/tyCo/1", "90.0.0.1", "90.0.0.10", 0, &pppOpt, NULL);
    }
The following routine generates the same results as the previous example. The difference is that the configuration options are obtained from a file rather than a structure.
pppFile = "phobos:/tmp/ppp_options";  /* PPP configuration options file */

void routine ()
    {
    pppInit (0, "/tyCo/1", "90.0.0.1", "90.0.0.10", 0, NULL, pppFile);
    }
where phobos:/tmp/ppp_options contains:
    passive
    no_pap
    no_chap
    no_vj
    lcp_echo_interval 30
    lcp_echo_failure 10

RETURNS

OK, or ERROR if the PPP interface cannot be initialized because the daemon task cannot be spawned or memory is insufficient.

pppDelete( )

NAME

pppDelete( ) - delete a PPP network interface

SYNOPSIS

void pppDelete
    (
    int unit /* PPP interface unit number to delete */
    )

DESCRIPTION

This routine deletes the Point-to-Point Protocol (PPP) network interface specified by the unit number unit.
A Link Control Protocol (LCP) terminate request packet is sent to notify the peer of the impending PPP link shut-down. The associated serial interface (tty) is then detached from the PPP driver, and the PPP interface is deleted from the list of network interfaces. Finally, all resources associated with the PPP link are returned to the VxWorks system.

RETURNS

N/A

pppLib

NAME

ROUTINES

DESCRIPTION

USER-CALLABLE ROUTINES

DATA ENCAPSULATION

LINK CONTROL PROTOCOL

NETWORK CONTROL PROTOCOLS

AUTHENTICATION

IMPLEMENTATION

INCLUDE FILES

SEE ALSO

ACKNOWLEDGEMENT

pppInit( )

NAME

SYNOPSIS

DESCRIPTION

IP ADDRESSES

CONFIGURATION OPTIONS STRUCTURE

CONFIGURATION OPTIONS FILE

AUTHENTICATION

EXAMPLES

RETURNS

SEE ALSO

pppDelete( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

SEE ALSO