Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
NG_PPP(4)	       FreeBSD Kernel Interfaces Manual		     NG_PPP(4)

NAME
     ng_ppp -- PPP protocol netgraph node type

SYNOPSIS
     #include <sys/types.h>
     #include <netgraph/ng_ppp.h>

DESCRIPTION
     The ppp node type performs	multiplexing for the PPP protocol.  It handles
     only packets that contain data, and forwards protocol negotiation and
     control packets to	a separate controlling entity (e.g., a user-land dae-
     mon).  This approach combines the fast dispatch of	kernel implementations
     with the configuration flexibility	of a user-land implementations.	 The
     PPP node type directly supports multi-link	PPP, Van Jacobson compression,
     PPP compression, PPP encryption, and the IP, IPX, and AppleTalk proto-
     cols.  A single PPP node corresponds to one PPP multi-link	bundle.

     There is a	separate hook for each PPP link	in the bundle, plus several
     hooks corresponding to the	directly supported protocols.  For compression
     and encryption, separate attached nodes are required to do	the actual
     work.  The	node type used will of course depend on	the algorithm negoti-
     ated.  There is also a bypass hook	which is used to handle	any protocol
     not directly supported by the node.  This includes	all of the control
     protocols:	LCP, IPCP, CCP,	etc.  Typically	this node is connected to a
     user-land daemon via a ng_socket(4) type node.

ENABLING FUNCTIONALITY
     In	general, the PPP node enables a	specific link or functionality when
     (a) a NGM_PPP_SET_CONFIG message has been received	which enables it, and
     (b) the corresponding hook(s) are connected.  This	allows the controlling
     entity to use either method (a) or	(b) (or	both) to control the node's
     behavior.	When a link is connected but disabled, traffic can still flow
     on	the link via the bypass	hook (see below).

LINK HOOKS
     During normal operation, the individual PPP links are connected to	hooks
     link0, link1, etc.	 Up to NG_PPP_MAX_LINKS	links are supported.  These
     device-independent	hooks transmit and receive full	PPP frames, which
     include the PPP protocol, address,	control, and information fields, but
     no	checksum or other link-specific	fields.

     On	outgoing frames, when protocol compression has been enabled and	the
     protocol number is	suitable for compression, the protocol field will be
     compressed	(i.e., sent as one byte	instead	of two).  Either compressed or
     uncompressed protocol fields are accepted on incoming frames.  Similarly,
     if	address	and control field compression has been enabled for the link,
     the address and control fields will be omitted (except for	LCP frames as
     required by the standards).  Incoming frames have the address and control
     fields stripped automatically if present.

     Since all negotiation is handled outside the PPP node, the	links should
     not be connected and enabled until	the corresponding link has reached the
     network phase (i.e., LCP negotiation and authentication have completed
     successfully) and the PPP node has	been informed of the link parameters
     via the NGM_PPP_LINK_CONFIG message.

     When a link is connected but disabled, all	received frames	are forwarded
     directly out the bypass hook, and conversely, frames may be transmitted
     via the bypass hook as well.  This	mode is	appropriate for	the link
     authentication phase.  As soon as the link	is enabled, the	PPP node will
     begin processing frames received on the link.

COMPRESSION AND	ENCRYPTION
     Compression is supported via two hooks, compress and decompress.  Com-
     pression and decompression	can be enabled by toggling the
     enableCompression and enableDecompression fields of the node configura-
     tion structure.  (See below.)  If enableCompression is set	to
     NG_PPP_COMPRESS_SIMPLE, then all outgoing frames are sent to the compress
     hook and all packets received on this hook	are expected to	be compressed,
     so	the COMPD tag is put on	them unconditionally.  If enableCompression is
     set to NG_PPP_COMPRESS_FULL, then packets received	on the compress	hook
     are resent	as is.	The compressor node should put the tag,	if the packet
     was compressed.  If enableDecompression is	set to
     NG_PPP_DECOMPRESS_SIMPLE, then the	node will sent to the decompress hook
     only those	frames,	that are marked	with the COMPD tag.  If
     enableDecompression is set	to NG_PPP_DECOMPRESS_FULL, then	the node will
     sent all incoming packets to the decompress hook.	Compression and	decom-
     pression can be completely	disabled by setting the	enableCompression and
     enableDecompression fields	to the NG_PPP_COMPRESS_NONE and
     NG_PPP_DECOMPRESS_NONE, respectively.

     Encryption	works exactly analogously via the encrypt and decrypt nodes.
     Data is always compressed before being encrypted, and decrypted before
     being decompressed.

     Only bundle-level compression and encryption is directly supported; link-
     level compression and encryption can be handled transparently by down-
     stream nodes.

VAN JACOBSON COMPRESSION
     When all of the vjc_ip, vjc_vjcomp, vjc_vjuncomp, and vjc_vjip hooks are
     connected,	and the	corresponding configuration flag is enabled, Van
     Jacobson compression and/or decompression will become active.  Normally
     these hooks connect to the	corresponding hooks of a single	ng_vjc(4)
     node.  The	PPP node is compatible with the	``pass through'' modes of the
     ng_vjc(4) node type.

BYPASS HOOK
     When a frame is received on a link	with an	unsupported protocol, or a
     protocol which is disabled	or for which the corresponding hook is uncon-
     nected, the PPP node forwards the frame out the bypass hook, prepended
     with a four byte prefix.  This first two bytes of the prefix indicate the
     link number on which the frame was	received (in network order).  For such
     frames received over the bundle (i.e., encapsulated in the	multi-link
     protocol),	the special link number	NG_PPP_BUNDLE_LINKNUM is used.	After
     the two byte link number is the two byte PPP protocol number (also	in
     network order).  The PPP protocol number is two bytes long	even if	the
     original frame was	protocol compressed.

     Conversely, any data written to the bypass	hook is	assumed	to be in this
     same format.  The four byte header	is stripped off, the PPP protocol num-
     ber is prepended (possibly	compressed), and the frame is delivered	over
     the desired link.	If the link number is NG_PPP_BUNDLE_LINKNUM the	frame
     will be delivered over the	multi-link bundle; or, if multi-link is	dis-
     abled, over the (single) PPP link.

     Typically when the	controlling entity receives an unexpected packet on
     the bypass	hook it	responds either	by dropping the	frame (if it is	not
     ready for the protocol) or	with an	LCP protocol reject (if	it does	not
     recognize or expect the protocol).

MULTILINK OPERATION
     To	enable multi-link PPP, the corresponding configuration flag must be
     set and at	least one link connected.  The PPP node	will not allow more
     than one link to be connected if multi-link is not	enabled, nor will it
     allow certain multi-link settings to be changed while multi-link opera-
     tion is active (e.g., short sequence number header	format).

     Since packets are sent as fragments across	multiple individual links, it
     is	important that when a link goes	down the PPP node is notified immedi-
     ately, either by disconnecting the	corresponding hook or disabling	the
     link via the NGM_PPP_SET_CONFIG control message.

     Each link has configuration parameters for	latency	(specified in mil-
     liseconds)	and bandwidth (specified in tens of bytes per second).	The
     PPP node can be configured	for round-robin	or optimized packet delivery.

     When configured for round-robin delivery, the latency and bandwidth val-
     ues are ignored and the PPP node simply sends each	frame as a single
     fragment, alternating frames across all the links in the bundle.  This
     scheme has	the advantage that even	if one link fails silently, some pack-
     ets will still get	through.  It has the disadvantage of sub-optimal over-
     all bundle	latency, which is important for	interactive response time, and
     sub-optimal overall bundle	bandwidth when links with different bandwidths
     exist in the same bundle.

     When configured for optimal delivery, the PPP node	distributes the	packet
     across the	links in a way that minimizes the time it takes	for the	com-
     pleted packet to be received by the far end.  This	involves taking	into
     account each link's latency, bandwidth, and current queue length.	There-
     fore these	numbers	should be configured as	accurately as possible.	 The
     algorithm does require some computation, so may not be appropriate	for
     very slow machines	and/or very fast links.

     As	a special case,	if all links have identical latency and	bandwidth,
     then the above algorithm is disabled (because it is unnecessary) and the
     PPP node simply fragments frames into equal sized portions	across all of
     the links.

HOOKS
     This node type supports the following hooks:

     link<N>	   Individual PPP link number <N>
     compress	   Connection to compression engine
     decompress	   Connection to decompression engine
     encrypt	   Connection to encryption engine
     decrypt	   Connection to decryption engine
     vjc_ip	   Connection to ng_vjc(4) ip hook
     vjc_vjcomp	   Connection to ng_vjc(4) vjcomp hook
     vjc_vjuncomp  Connection to ng_vjc(4) vjuncomp hook
     vjc_vjip	   Connection to ng_vjc(4) vjip	hook
     inet	   IP packet data
     ipv6	   IPv6	packet data
     atalk	   AppleTalk packet data
     ipx	   IPX packet data
     bypass	   Bypass hook;	frames have a four byte	header consisting of a
		   link	number and a PPP protocol number.

CONTROL	MESSAGES
     This node type supports the generic control messages, plus	the following:

     NGM_PPP_SET_CONFIG
	  This command configures all aspects of the node.  This includes
	  enabling multi-link PPP, encryption, compression, Van	Jacobson com-
	  pression, and	IP, IPv6, AppleTalk, and IPX packet delivery.  It
	  includes per-link configuration, including enabling the link,	set-
	  ting latency and bandwidth parameters, and enabling protocol field
	  compression.	Note that no link or functionality is active until the
	  corresponding	hook is	also connected.	 This command takes a struct
	  ng_ppp_node_conf as an argument:

	  /* Per-link config structure */
	  struct ng_ppp_link_conf {
	    u_char    enableLink;     /* enable	this link */
	    u_char    enableProtoComp;/* enable	protocol field compression */
	    u_char    enableACFComp;  /* enable	addr/ctrl field	compression */
	    u_int16_t mru;	      /* peer MRU */
	    u_int32_t latency;	      /* link latency (in milliseconds)	*/
	    u_int32_t bandwidth;      /* link bandwidth	(in bytes/second) */
	  };

	  /* Bundle config structure */
	  struct ng_ppp_bund_conf {
	    u_int16_t mrru;		      /* multilink peer	MRRU */
	    u_char    enableMultilink;	      /* enable	multilink */
	    u_char    recvShortSeq;	      /* recv multilink	short seq # */
	    u_char    xmitShortSeq;	      /* xmit multilink	short seq # */
	    u_char    enableRoundRobin;	      /* xmit whole packets */
	    u_char    enableIP;		      /* enable	IP data	flow */
	    u_char    enableIPv6;	      /* enable	IPv6 data flow */
	    u_char    enableAtalk;	      /* enable	AppleTalk data flow */
	    u_char    enableIPX;	      /* enable	IPX data flow */
	    u_char    enableCompression;      /* enable	PPP compression	*/
	    u_char    enableDecompression;    /* enable	PPP decompression */
	    u_char    enableEncryption;	      /* enable	PPP encryption */
	    u_char    enableDecryption;	      /* enable	PPP decryption */
	    u_char    enableVJCompression;    /* enable	VJ compression */
	    u_char    enableVJDecompression;  /* enable	VJ decompression */
	  };

	  struct ng_ppp_node_conf {
	    struct ng_ppp_bund_conf   bund;
	    struct ng_ppp_link_conf   links[NG_PPP_MAX_LINKS];
	  };

     NGM_PPP_GET_CONFIG
	  Returns the current configuration as a struct	ng_ppp_node_conf.

     NGM_PPP_GET_LINK_STATS
	  This command takes a two byte	link number as an argument and returns
	  a struct ng_ppp_link_stat containing statistics for the correspond-
	  ing link.  Here NG_PPP_BUNDLE_LINKNUM	is a valid link	number corre-
	  sponding to the multi-link bundle.

     NGM_PPP_GET_LINK_STATS64
	  Same as NGM_PPP_GET_LINK_STATS but returns struct ng_ppp_link_stat64
	  containing 64bit counters.

     NGM_PPP_CLR_LINK_STATS
	  This command takes a two byte	link number as an argument and clears
	  the statistics for that link.

     NGM_PPP_GETCLR_LINK_STATS
	  Same as NGM_PPP_GET_LINK_STATS, but also atomically clears the sta-
	  tistics as well.

     NGM_PPP_GETCLR_LINK_STATS64
	  Same as NGM_PPP_GETCLR_LINK_STATS but	returns	struct
	  ng_ppp_link_stat64 containing	64bit counters.

     This node type also accepts the control messages accepted by the
     ng_vjc(4) node type.  When	received, these	messages are simply forwarded
     to	the adjacent ng_vjc(4) node, if	any.  This is particularly useful when
     the individual PPP	links are able to generate NGM_VJC_RECV_ERROR messages
     (see ng_vjc(4) for	a description).

SHUTDOWN
     This node shuts down upon receipt of a NGM_SHUTDOWN control message, or
     when all hooks have been disconnected.

SEE ALSO
     netgraph(4), ng_async(4), ng_iface(4), ng_mppc(4),	ng_pppoe(4),
     ng_vjc(4),	ngctl(8)

     W.	Simpson, The Point-to-Point Protocol (PPP), RFC	1661.

     K.	Sklower, B. Lloyd, G. McGregor,	D. Carr, and T.	Coradetti, The PPP
     Multilink Protocol	(MP), RFC 1990.

HISTORY
     The ng_ppp	node type was implemented in FreeBSD 4.0.

AUTHORS
     Archie Cobbs <archie@FreeBSD.org>

FreeBSD	10.1		      September	24, 2012		  FreeBSD 10.1

NAME | SYNOPSIS | DESCRIPTION | ENABLING FUNCTIONALITY | LINK HOOKS | COMPRESSION AND ENCRYPTION | VAN JACOBSON COMPRESSION | BYPASS HOOK | MULTILINK OPERATION | HOOKS | CONTROL MESSAGES | SHUTDOWN | SEE ALSO | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ng_ppp&sektion=4&manpath=FreeBSD+9.3-RELEASE>

home | help