![[Contents]](icons/contents.gif){kind=icon}
![[Index]](icons/index.gif){kind=icon}
![[Prev]](icons/prev.gif){kind=icon}
![[Next]](icons/next.gif){kind=icon}
This PPP implementation is very limited. It works with a serial driver only, not with other such options as a modem or an Ethernet driver. It does not provide an API for modem support, and modem drivers are not provided for it. It is limited to sixteen connections. It also supports only standard CHAP, not the Microsoft CHAP extensions.
This implementation of PPP was originally intended for debugging purposes and to provide an additional means for downloading a boot image. This version of PPP should not be used for remote access applications.
The VxWorks target can support IP communication with the host operating system over serial connections using the following protocols:
SLIP and CSLIP (SLIP with compressed headers) provide a simple form of encapsulation for IP datagrams on serial lines. Using SLIP or CSLIP as a network interface driver is a straightforward way to use TCP/IP software with point-to-point configurations such as long-distance telephone lines or RS-232 serial connections between machines.
To use SLIP with your VxWorks target, make the following configuration changes (for more information on configuring VxWorks, see the Tornado User's Guide: Projects):
|
|||||||||||||||||||
The following is a list of Requests for Comments (RFCs) associated with this unsupported PPP implementation:
The USENET news group, comp.protocols.ppp, is dedicated to the discussion of PPP-related issues. Information presented in this forum is often of a general nature (such as equipment, setup, or troubleshooting), but technical details concerning specific PPP implementations are discussed as well.
Configuring your environment for PPP requires both host and target software installation and configuration. See your host's operating system manual for information on installing and configuring PPP on your host.1
To include the default PPP configuration, configure VxWorks with PPP support. The relevant configuration parameter is INCLUDE_PPP.
You can include the optional DES cryptographic package for use with the Password Authentication Protocol (PAP). The relevant configuration parameter is INCLUDE_PPP_CRYPT. It is not included in the standard Tornado Release; contact your WRS Sales Representative to inquire about the availability of this optional package.
The DES package allows user passwords to be stored in encrypted form on the VxWorks target. If the package is installed, then it is useful only when the VxWorks target is acting as a PAP server, that is, when VxWorks is authenticating the PPP peer. Its absence does not preclude the use of PAP. For detailed information about using the DES package with PAP, see Using PAP, p.307).
Each of these methods is described in a section that follows. For brief descriptions of the various PPP options, see C.3.4 PPP Option Descriptions, p.312.
|
|||||||||||||||||||
First, make sure the PPP_OPTIONS_STRUCT configuration parameter is set (it is set by default). Unless PPP_OPTIONS_STRUCT configuration parameter is set, these configuration options cannot be enabled.
Then, specify the default serial interface that will be used by usrPPPInit( ) by setting the PPP_TTY configuration parameter. Configuration options can be selected using configuration constants only when usrPPPInit( ) is invoked to initialize PPP. Specify the number of seconds usrPPPInit( ) will wait for a PPP link to be established between a target and peer by defining the PPP_CONNECT_DELAY configuration parameter. Table 1 lists the principal configuration parameters used with PPP.
The full list of configuration options available with PPP appears under C.3.4 PPP Option Descriptions, p.312. By default, all of these options are disabled.
Setting PPP_OPTIONS_STRUCT, PPP_TTY, and PPP_CONNECT_DELAY as well as any additional configuration parameters, constitutes a modification to the configuration. These changes do not actually take effect until after you have recompiled VxWorks and initialized PPP. To initialize PPP, call usrPPPInit( ). You can make this call manually from a target shell (see Initializing a PPP Link, p.304).
PPP options may be set at run-time by filling in a PPP options structure and passing the structure location to the pppInit( ) routine. This routine is the standard entry point for initializing a PPP link (see Initializing a PPP Link, p.304).
The PPP options structure is typedefed to PPP_OPTIONS, and its definition is located in h/netinet/ppp/options.h, which is included through h/pppLib.h.
The first field of the structure is an integer, flags, which is a bit field that holds the ORed value of the OPT_option macros displayed under C.3.4 PPP Option Descriptions, p.312. Definitions for OPT_option are located in h/netinet/ppp/options.h. The remaining structure fields in column 2 are character pointers to the various PPP options specified by a string.
The following code fragment is one way to set configuration options using the PPP options structure. It 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. The VJ compression and authentication options have been disabled, and LCP (Link Control Protocol) 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);
}
PPP options are most conveniently set using an options file. There is one restriction: the options file must be readable by the target without there being an active PPP link. Therefore the target must either have a local disk or RAM disk or an additional network connection. For more information about using file systems, see VxWorks Programmer's Guide: Local File Systems.
This configuration method can be used with either usrPPPInit( ) or pppInit( ). It also can be used to modify the selection of PPP options previously configured using configuration parameters or the option structure PPP_OPTION.
When using usrPPPInit( ) to initialize PPP, define the configuration parameter PPP_OPTIONS_FILE to be the absolute pathname of the options file (NULL by default). When using pppInit( ), pass in a character string that specifies the absolute pathname of the options file.
The options file format is one option per line; comment lines begin with #. For a description of option syntax, see the manual entry for pppInit( ).
The following code fragment generates the same results as the code example in C.3.4 PPP Option Descriptions, p.312. The difference is that the configuration options are obtained from a file rather than a structure.
pppFile = "mars:/tmp/ppp_options"; /* PPP config. options file */
void routine ()
{
pppInit (0, "/tyCo/1", "90.0.0.1", "90.0.0.10", 0, NULL, pppFile);
}
In this example, mars:/tmp/ppp_options is a file that contains the following:
passive
no_pap
no_chap
no_vj
lcp_echo_interval 30
lcp_echo_failure 10
A PPP link is initialized by calls to either usrPPPInit( ) or pppInit( ). When either of these routines is invoked, the remote peer should be initialized. When a peer is running in passive mode, it must be initialized first (see C.3.4 PPP Option Descriptions, p.312.).
You can initialize the PPP interface by calling usrPPPInit( ):
Use either syntax when calling usrPPPInit( ):
usrPPPInit ("bootDevice", unitNum, "localIPAddress", "remoteIPAddress")
usrPPPInit ("bootDevice", unitNum, "localHostName", "remoteHostName")
You can use host names in usrPPPInit( ) provided the hosts have been previously added to the host database. For example, you can call usrPPPInit( ) in the following way:
usrPPPInit ("ppp=/tyCo/1,38400", 1, "147.11.90.1", "147.11.90.199")
The usrPPPInit( ) routine calls pppInit( ), which initializes PPP with the configuration parameters that were specified at compile-time (see Setting PPP Options when Configuring VxWorks, p.301). The pppInit( ) routine can be called multiple times to initialize multiple channels.2 The connection timeout is specified by PPP_CONNECT_DELAY. The return value of this routine indicates whether the link has been successfully established. If the return value is OK, the network connection should be fully operational.
The pppInit( ) routine is the standard entry point for initializing a PPP link. All available PPP options can be set using parameters specified for this routine (see C.3.4 PPP Option Descriptions, p.312). Unlike usrPPPInit( ), the return value of pppInit( ) does not indicate the status of the PPP link; it merely reports whether the link could be initialized. To check whether the link is actually established, call pppInfoGet( ) and make sure that the state of IPCP is OPENED. The following code fragment demonstrates use of this mechanism for PPP unit 2:
PPP_INFO pppInfo;
if ((pppInfoGet (2, &pppInfo) == OK) &&
(pppInfo.ipcp_fsm.state == OPENED))
return (OK); /* link established */
else
return (ERROR); /* link down */
Merely deleting the VxWorks tasks that control PPP or rebooting the target severs the link only at the TCP/IP stack, but does not delete the link on the remote peer end.
The return value of pppDelete( ) does not indicate the status of the PPP link. To check whether the link is actually terminated, call pppInfoGet( ) and make sure the return value is ERROR. The following code fragment demonstrates the usage of this mechanism for PPP unit 4:
PPP_INFO pppInfo;
if (pppInfoGet (4, &pppInfo) == ERROR)
return (OK); /* link terminated */
else
return (ERROR); /* link still up */
|
|
|||||||||||||||||||
In this implementation, the default behavior of PPP is to provide authentication when requested by a peer but not to require authentication from a peer. If additional security is required, choose PAP or CHAP by enabling the corresponding option. This PPP implementation can act as a client (the peer authenticating itself) or a server (the authenticator).
Authentication for both PAP and CHAP is based on secrets, selected from a secrets file or from the secrets database built by the user (which can hold both PAP and CHAP secrets). A secret is represented by a record, which itself is composed of fields. The secrets file and the secrets database contain secrets that authenticate other clients, as well as secrets used to authenticate the VxWorks client to its peer. In the case that a VxWorks target cannot access the secrets file through the file system, use pppSecretAdd( ) to build a secrets database.
Secrets files for PAP and CHAP use identical formats. A secrets record is specified in a file by a line containing at least three words that specify the contents of the fields client, server, and secret, in that order. For PAP, secret is a password that must match the password entered by the client seeking PAP authentication. For CHAP, both client and server must have identical secrets records in their secrets files; the secret consists of a string of one or more words (for example, "an unguessable secret").
Table 2 is an example of a secrets file. It could be either a PAP or CHAP secrets file, since their formats are identical.
|
|
|||||||||||||||||||
|
|
|||||||||||||||||||
|
|
|||||||||||||||||||
At the time of authentication, for a given record, PPP interprets any words following client, server, and secret as acceptable IP addresses for the client and secret specified. If there are only three words on the line, it is assumed that any IP address is acceptable; to disallow all IP addresses, use a dash (-). If the secret starts with an @, what follows is assumed to be the name of a file from which to read a secret. An asterisk (*) as the client or server name matches any name. When authentication is initiated, a best-match algorithm is used to find a match to the secret, meaning that, given a client and server name, the secret returned is for the closest match found.
On receiving an authentication request, PPP checks for the existence of secrets either in an internal secrets database or in a secrets file. If PPP does not find the secrets information, the connection is terminated.
The secrets file contains secrets records used to authenticate the peer, and those used to authenticate the VxWorks client to the peer. Selection of a record is based on the local and remote names. By default, the local name is the host name of the VxWorks target, unless otherwise set to a different name by the option local_auth_name in the options file. The remote name is set to a NULL string by default, unless otherwise set to a name specified by the option remote_auth_name in the options file. (Both local_auth_name and remote_auth_name can be specified in two other forms, as can other configuration options listed under C.3.4 PPP Option Descriptions, p.312.)
The default behavior of PPP is to authenticate itself if requested by a peer but not to require authentication from a peer. For PPP to authenticate itself in response to a server's PAP authentication request, it only requires access to the secrets. For PPP to act as an authenticator, you must turn on the PAP configuration option.
Secrets can be declared in a file or built into a database. The secrets file for PAP can be specified in one of the following ways:
pap_file /xxx/papSecrets
If the VxWorks target is unable to access the secrets file, call pppSecretAdd( ) to build a secrets database.
If PPP requires the peer to authenticate itself using PAP, the necessary configuration option can be set in one of the following ways:
require_pap
Secrets records are first searched in the secrets database; if none are found there, then the PAP secrets file is searched. The search proceeds as follows:
PPP looks for a secrets record with a client field that matches the user name specified in the PAP authentication request packet and a server field matching the local name. If the password does not match the secrets record supplied by the secrets file or the secrets database, it is encrypted, provided the optional DES cryptographic package is installed. Then it is checked against the secrets record again. Secrets records for authenticating the peer can be stored in encrypted form if the optional DES package is used. If the login option was specified, the user name and the password specified in the PAP packet sent by the peer are checked against the system password database. This enables restricted access to certain users.
The default behavior of PPP is to authenticate itself if requested by a peer but not to require authentication from a peer. For PPP to authenticate itself in response to a server's CHAP authentication request, it only requires access to the secrets. For PPP to act as an authenticator, you must turn on the CHAP configuration option.
CHAP authentication is instigated when the authenticator sends a challenge request packet to the peer, which responds with a challenge response. Upon receipt of the challenge response from the peer, the authenticator compares it with the expected response and thereby authenticates the peer by sending the required acknowledgment. CHAP uses the MD5 algorithm for evaluation of secrets.
The secrets file for CHAP can be specified in any of the following ways:
chap_file /xxx/chapSecrets
If PPP requires the peer to authenticate itself using CHAP, the necessary configuration option can be set in one of the following ways:
require_chap
Secrets are first searched in the secrets database; if none are found there, then the CHAP secrets file is searched. The search proceeds as follows:
PPP provides connect and disconnect hooks for use with user-specific software. Use the pppHookAdd( ) routine to add a connect hook that executes software before initializing and establishing the PPP connection or a disconnect hook that executes software after the PPP connection has been terminated. The pppHookDelete( ) routine deletes connect and disconnect hooks.
The routine pppHookAdd( ) takes three arguments: the unit number, a pointer to the hook routine, and the hook type (PPP_HOOK_CONNECT or PPP_HOOK_DISCONNECT). The routine pppHookDelete( ) takes two arguments: the unit number and the hook type. The hook type distinguishes between the connect hook and disconnect hook routines.
Two arguments are used to call the connect and disconnect hooks: unit, which is the unit number of the PPP connection, and fd, the file descriptor associated with the PPP channel. If the user hook routines return ERROR, then the link is gracefully terminated and an error message is logged.
|
|
|||||||||||||||||||
The code in Example 1 demonstrates how to hook the example routines, connectRoutine( ) and disconnectRoutine( ), into the PPP connection establishment mechanism and termination mechanism, respectively.
Example 1 : Using Connect and Disconnect Hooks
#include <vxWorks.h>
#include <pppLib.h>
void attachRoutine(void);
static int connectRoutine(int, int);
static int disconnectRoutine(int, int);
void attachRoutine(void)
{
/* add connect hook to unit 0 */
pppHookAdd(0, connectRoutine, PPP_HOOK_CONNECT);
/* add disconnect hook to unit 0 */
pppHookAdd(0, disconnectRoutine, PPP_HOOK_DISCONNECT);
}
static int connectRoutine
(
int unit,
int fd
)
BOOL connectOk = FALSE;
/* user specific connection code */
{
.......................
connectOk = TRUE;
if(connectOk)
{
return(OK);
else
return(ERROR);
}
static int disconnectRoutine
(
int unit,
int fd
)
{
BOOL disconnectOk = FALSE;
/* user specific code */
{
............................................
disconnectOk = TRUE;
}
if(disconnectOk)
return(OK);
else
return(ERROR);
}
Because of the complex nature of PPP, you may encounter problems using it in conjunction with VxWorks. Give yourself the opportunity to get familiar with running VxWorks configured with PPP by starting out using a default configuration. Additional options for the local peer should be disabled. (You can always add these options later.) Problems with PPP generally occur in either of two areas: when establishing links and when using authentication. The following sections offer checklists for troubleshooting errors that have occurred during these processes.
The link is the basic operating element of PPP; a proper connection ensures the smooth functioning of PPP, as well as VxWorks. The following steps should help resolve simple problems encountered when establishing a link.
% usrPPPInit
If no arguments are supplied, the target configures the default settings. If a timeout error occurs, reconfigure VxWorks with a larger connect delay time. The relevant configuration parameter is PPP_CONNECT_DELAY. By default, the delay is set to 15 seconds, which may not be sufficient in some environments.
Authentication is one of the more robust features of this PPP implementation. The following steps may help you troubleshoot basic authentication problems.
This section lists all the configurable options supported by this PPP implementation. You can configure each of these options from three different locations:
If you set the same option using more than one of the above methods, the option settings specified in the options file PPP_OPTIONS_FILE take precedence over any set using the VxWorks image configuration tool or by passing a PPP_OPTIONS structure into pppInit( ). For example:
|
|
|||||||||||||||||||
|
|
|||||||||||||||||||
|
|
|||||||||||||||||||
1: If your host operating system does not provide PPP facilities, you can use a publicly available implementation. One popular implementation for SunOS 4.1.x (and several other hosts) is the PPP version 2.1.2 implementation provided in the unsupported/ppp-2.1.2 directory. This code is publicly available and is included only as a convenience. This code is not supported by Wind River Systems.
2: The usrPPPInit( ) routine can specify the unit number as a parameter. If this number is omitted, PPP defaults to 0.