NAME

PPP Server – pppd

SYNOPSIS

#include <netinet/ppp.h>

DESCRIPTION

Point-to-Point Protocol (PPP) is a data link protocol commonly used in establishing a direct connection between two networking nodes. It uses Link Control Protocol (LCP) to negotiate connection capabilities and to establish, configure, and test the link.

A TCP server talks across Ethernet to communicate to other nodes on a subnet when using IPv4. If the node that a user wants to communicate with is not on the subnet, then the packet will be routed through the gateway node to the remote node. To perform this tcp-server supports packet routing between interfaces.

If a subnet is remote, and is connected via a wireless link like GPRS or another wireless or wireline link, two more aspects come into play. First the protocol to communicate over serial lines must be used. It is called PPP. Now the node which hosts PPP and another Ethernet becomes a gateway and must route packets between the inerfaces.

The second aspect of setting up a serial link is that there is generally a modem which must be initialized and connected first before the network is setup. If there is a link failure on the modem, this link failure must be communicated and the modem restarted before the link can be brought back up. The command set that is used is called an AT command set for historical reasons. These are relatively standard commands widely used for a variety of purposes in communications and industrial control.

Together with pppd can be used Network Address Translation (NAT) mechanism. Node can connect to the ISP and provide access to the Internet all the nodes on the LAN via NAT. This technology presents in two Unison components: simple NAT and packet filter pf.

Pppd requires a configuration record for initialization related to authentication which is setup by an interface call or with direct structure modification.

The basic features of the pppd are:

1. • PPP

1. • Good authentication

1. • A PPP implementation architecture which enables modem configuration using AT or other commands before PPP is run.

1. • Off the shelf authentication

1. • User management features

The basic steps for configuration pppd are:

1. 1. Call

pppInit()

1. to start the server.

1. 2. Modify values in the

ppp_settings

1. structure.

1. 3. Setup the authorization using

pppSetAuth()

1. .

1. 4. Use

pppOpen

1. to start the link using a particular serial line, specifying the callback function for errors handling.

5. Now you should be up and running.

To get the status while the link is up, call pppIOCTL().

If errors occur, the callback function is called with and error code and the application programmer must take appropriate action. If an error occurs because the link went down, the connection is automatically closed.

To close the link at any time, simply call pppClose() or pppSIGHUP() if the serial link has been dropped.

User functions

void pppInit(void);
Initialize the PPP subsystem.

void pppSetAuth(enum pppAuthType authType, const char *user, const char *passwd);
Set the authorization: authentication type, user name and password. Authentication can be:

    enum pppAuthType {
        PPPAUTHTYPE_NONE,
        PPPAUTHTYPE_ANY,
        PPPAUTHTYPE_PAP,
        PPPAUTHTYPE_CHAP
    };

int pppOpen(char *tty_name, int prio, void (*linkStatusCB)(void *ctx, int errCode, void *arg), void *linkStatusCtx);
Open a new PPP connection using the given I/O device tty_name. This initializes the PPP control block and start PPP thread with priority prio. When errors will occur will be called callback function linkStatusCB with linkStatusCtx context and appropriate error code and argument. Error code can be:

    /* Error codes. */
    #define PPPERR_NONE 0               /* No error. */
    #define PPPERR_PARAM -1             /* Invalid parameter. */
    #define PPPERR_OPEN -2              /* Unable to open PPP session. */
    #define PPPERR_DEVICE -3            /* Invalid I/O device for PPP. */
    #define PPPERR_ALLOC -4             /* Unable to allocate resources. */
    #define PPPERR_USER -5              /* User interrupt. */
    #define PPPERR_CONNECT -6           /* Connection lost. */
    #define PPPERR_AUTHFAIL -7          /* Failed authentication challenge. */
    #define PPPERR_PROTOCOL -8          /* Failed to meet protocol. */

int pppClose(int pd);
Close a PPP connection and release the descriptor. Any outstanding packets in the queues are dropped. Return 0 on success, an error code on failure.
Note:
pppClose() is a friendly way to shutdown the link, and inform the other end that we have shutdown.

void pppSigHUP(int pd);
Indicate to the PPP process that the line has disconnected.
Note:
pppSigHUP() is to be used when the serial link has been dropped. Maybe the communication to the modem has died.

int pppIOCtl(int pd, int cmd, void *arg);
Get and set parameters for the given connection. Return 0 on success, an error code on failure.
Possible commands:
PPPCTLG_UPSTATUS – get the up status – 0 down else up
PPPCTLS_ERRCODE – set the error code
PPPCTLG_ERRCODE – get the error code
PPPCTLG_FD – get the fd associated with the ppp
PPPCTLG_STATS – get the ppp statistics

Structure for pppd statistics:

    struct pppd_stats {
        unsigned long   pkts_in;
        unsigned long   pkts_out;
        unsigned long   pkts_drop;
        unsigned long   pkts_lenerr;
        unsigned long   pkts_chkerr;
    };

u_int pppMTU(int pd);
Return the Maximum Transmission Unit for the given PPP connection.

struct ppp_addrs *pppGetIP(int pd);
Get all IP addresses for PPP connection.

    struct ppp_addrs {
        struct in_addr our_ipaddr, his_ipaddr, netmask, dns1, dns2;
    };

void pppSetServerDefaultIP(uint_32 ip);
Set default IP addresses for PPP server. Some PPP servers do not send to client self IP-address, so pppd use default address, defined by user.

Additional parameters

pppd has some additional parameters in structure ppp_settings:
ppp_settings.idle_time_limit – shut down link if idle for this long
ppp_settings.maxconnect – maximum connect time (seconds)
ppp_settings.flow_ctl – flow control mode
Flow control codes:

    #define FLCTL_NONE      0
    #define FLCTL_XONXOFF   1
    #define FLCTL_CRTSCTS   2

Connection close callbacks

If a connection is closed, the callback gets called twice in most cases. The following is a summary of the conditions and the errors generated.

Closed by the remote side.
ISP normally closes ppp connection. User will get 2 callback events:
– PPPERR_CONNECT (Connection lost)
– PPPERR_PROTOCOL (Failed to meet protocol)

Closed by user command.
User closed connection by command pppClose(). User will get 2 callback events:
– PPPERR_CONNECT (Connection lost)
– PPPERR_USER (User interrupt)

Closed by user max time connect expired.
User can set max time for the connection:
ppp_settings.maxconnect = 10; // time in seconds
User will get 2 callback events:
– PPPERR_CONNECT (Connection lost)
– PPPERR_PROTOCOL (Failed to meet protocol)

Closed by link failure.
pppd automatically sends control link packets. If pppd does not get a response from remote side, the user will get 2 callback events:
– PPPERR_CONNECT (Connection lost)
– PPPERR_PROTOCOL (Failed to meet protocol)

After any close event, the user can open the modem tty port and try to reconnect to ISP using AT commands.

EXAMPLE

Setup and start pppd:

int start_pppd(void)
{
	int i, res;

	// Init PPP structures
	pppInit();

	// Init other PPP options
	pppSetAuth(PPPAUTHTYPE_PAP, "user", "passwd");
	ppp_settings.flow_ctl = FLCTL_XONXOFF;


	// Start PPP thread
	ppp_id = pppOpen("/dev/ttyS2", PPPD_PRIO, ppp_callback, (void*)1);


	// check while PPP set status to 'up'
	if (ppp_id >= 0)
	{
		for (i = 0; i < 5; i++)
		{
			sleep(1);
			pppIOCtl(ppp_id, PPPCTLG_UPSTATUS, &res);
			if (res == 1)
				break;
		}
		if (i == 5)
		{
			pppClose(ppp_id);
			sleep(5);
			return -1;
		}
	}
	else
		return -1;

	return 0;
}

Callback function:

void ppp_callback(void *ctx, int errCode, void *arg)
{
	struct ppp_addrs *addr;
	struct pppd_stats *stat;

	printf("   ***   ppp_callback: ctx: 0x%x, err: %d, arg: 0x%x\n", (int)ctx, errCode, (int)arg);

	switch (errCode)
	{
		case PPPERR_NONE:
			printf("No error.\n");
			addr = (struct ppp_addrs *)arg;
			printf("   ***   our ipaddr = %s\n", inet_ntoa(addr->our_ipaddr));
			printf("   ***   his ipaddr = %s\n", inet_ntoa(addr->his_ipaddr));
			printf("   ***   netmask = %s\n", inet_ntoa(addr->netmask));
			printf("   ***   dns1 = %s\n", inet_ntoa(addr->dns1));
			printf("   ***   dns2 = %s\n", inet_ntoa(addr->dns2));
			break;
		case PPPERR_PARAM:
			printf("Invalid parameter.\n");
			break;
		case PPPERR_OPEN:
			printf("Unable to open PPP session.\n");
			break;
		case PPPERR_DEVICE:
			printf("Invalid I/O device for PPP.\n");
			break;
		case PPPERR_ALLOC:
			printf("Unable to allocate resources.\n");
			break;
		case PPPERR_USER:
			printf("User interrupt.\n");
			break;
		case PPPERR_CONNECT:
			printf("Connection lost.\n");
			pppIOCtl(ppp_id, PPPCTLG_STATS, &stat);
			printf("   ***   in packets = %lu\n", stat->pkts_in);
			printf("   ***   out packets = %lu\n", stat->pkts_out);
			printf("   ***   drop packets = %lu\n", stat->pkts_drop);
			printf("   ***   len error packets = %lu\n", stat->pkts_lenerr);
			printf("   ***   checksum error packets = %lu\n", stat->pkts_chkerr);
			break;
		case PPPERR_AUTHFAIL:
			printf("Failed authentication challenge.\n");
			break;
		case PPPERR_PROTOCOL:
			printf("Failed to meet protocol.\n");
			break;
		default:
			printf("Unknown callback!!!\n");
			break;
	}
}

NOTES

There is a demo PPP available for the Unison and DSPnano NAT which is found in installdir/demos.

SEE ALSO

tcpd, tcpd_dual, simple NAT, pf

Home page (Servers)