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

FreeBSD Manual Pages

  
 
  

home | help
NG_PIPE(4)	       FreeBSD Kernel Interfaces Manual		    NG_PIPE(4)

NAME
     ng_pipe --	Traffic	manipulating netgraph node type

SYNOPSIS
     #include <netgraph/ng_pipe.h>

DESCRIPTION
     The pipe node type	manipulates traffic by emulating bandwidth and delay,
     as	well as	random packet losses.

HOOKS
     This node type supports the following hooks:

     upper  Hook leading to upper layer	protocols.

     lower  Hook leading to lower layer	protocols.

     Traffic flowing from upper	to lower is considered downstream traffic.
     Traffic flowing from lower	to upper is considered upstream	traffic.

MODE OF	OPERATION
     Data received on a	hook - both in upstream	and downstream direction - is
     put into an inbound queue.	 If inbound queue is full, discard one frame
     depending on dropping policy (from	the head or from the tail of the
     queue).

     There are three mutually exclusive	modes for the input queue:

     First In First Out	(FIFO)
	  A single queue holds packets in chronological	order.

     Weighted fair queuing (WFQ)
	  There	are multiple queues for	different traffic flows	(based on IPv4
	  IPs).	 The longest queue is truncated	if necessary.  This approach
	  assumes that the stalling flow is the	flow with the most packets
	  currently on hold.

     Deficit Round Robin (DRR)
	  This mode is similar to WFQ, but packets are not taken out in	strict
	  chronological	order.	In principle oldest packets come first,	but
	  not too many packets from the	same flow.

     It	is possible to configure a duplication probability.  As	the dice de-
     cides, the	currently active packet	stays in the queue while a copy	of the
     packet is sent out.  Nothing prevents a packet from being duplicated mul-
     tiple times.

     Packets are dropped with an increasing probability	depending on the size
     of	the packet, if a ber (bit error	rate) is configured.

     Surviving packets are delayed by the time the packet would	need to	travel
     through a link of the configured bandwidth.  If this outbound queue is
     full, the packet is dropped.

CONTROL	MESSAGES
     This node type supports the generic control messages and the following
     specific messages.

     NGM_PIPE_SET_CFG (setcfg)
	  Set node configuration to the	one specified in struct	ng_pipe_cfg

	  Note:	To set a value to zero,	specify	-1 instead.  This allows omit-
	  ting configuration values, which should not be modified.

     NGM_PIPE_GET_CFG (getcfg)
	  Return current node configuration as struct ng_pipe_cfg

	  struct ng_pipe_cfg {
	    u_int64_t  bandwidth;     /* bits per second */
	    u_int64_t  delay;	      /* additional delay, usec	*/
	    u_int32_t  header_offset; /* offset	of IP header in	bytes */
	    u_int32_t  overhead;      /* assumed L2 overhead in	bytes */
	    struct ng_pipe_hookcfg  downstream;
	    struct ng_pipe_hookcfg  upstream;
	  };

	  /* Config structure for one hook */
	  struct ng_pipe_hookcfg {
	    u_int64_t  bandwidth;	/* bits	per second */
	    u_int64_t  ber;		/* avg.	interval between bit errors (1 / BER) */
	    u_int32_t  qin_size_limit;	/* number of queue items */
	    u_int32_t  qout_size_limit;	/* number of queue items */
	    u_int32_t  duplicate;	/* probability in % */
	    u_int32_t  fifo;		/* 0 = off, 1 =	on */
	    u_int32_t  drr;		/* 0 = off, 1 =	2048 bytes, or x bytes */
	    u_int32_t  wfq;		/* 0 = off, 1 =	on */
	    u_int32_t  droptail;	/* 0 = off, 1 =	on */
	    u_int32_t  drophead;	/* 0 = off, 1 =	on */
	  };

     NGM_PIPE_GET_STATS	(getstats)
	  Return node statistics as struct ng_pipe_stats

	  /* Statistics	structure for one hook */
	  struct ng_pipe_hookstat {
	    u_int64_t  fwd_octets;
	    u_int64_t  fwd_frames;
	    u_int64_t  in_disc_octets;
	    u_int64_t  in_disc_frames;
	    u_int64_t  out_disc_octets;
	    u_int64_t  out_disc_frames;
	  };

	  /* Statistics	structure returned by NGM_PIPE_GET_STATS */
	  struct ng_pipe_stats {
	    struct ng_pipe_hookstat  downstream;
	    struct ng_pipe_hookstat  upstream;
	  };

     NGM_PIPE_CLR_STATS	(clrstats)
	  Clear	node statistics.

     NGM_PIPE_GETCLR_STATS (getclrstats)
	  Atomically return and	clear node statistics.

     NGM_PIPE_GET_RUN (getrun)
	  Return node statistics as struct ng_pipe_run

	  /* Runtime structure for one hook */
	  struct ng_pipe_hookrun {
	    u_int32_t  fifo_queues;
	    u_int32_t  qin_octets;
	    u_int32_t  qin_frames;
	    u_int32_t  qout_octets;
	    u_int32_t  qout_frames;
	  };

	  /* Runtime structure returned	by NGM_PIPE_GET_RUN */
	  struct ng_pipe_run {
	    struct ng_pipe_hookrun  downstream;
	    struct ng_pipe_hookrun  upstream;
	  };

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

EXAMPLES
     Limit outgoing data rate over fxp0	Ethernet interface to 20Mbps in	fifo
     mode and incoming to 50kbps in drr	mode and 2% duplicate probability.

	   /usr/sbin/ngctl -f- <<-SEQ
	     mkpeer fxp0: pipe lower lower
	     name fxp0:lower fxp0_pipe
	     connect fxp0: fxp0_pipe: upper upper
	     msg fxp0_pipe: setcfg { downstream={ bandwidth=20000000 fifo=1 } }
	     msg fxp0_pipe: setcfg { upstream={	bandwidth=500000 drr=1 duplicate=2 } }
	   SEQ

SEE ALSO
     netgraph(4), ngctl(8)

AUTHORS
     Lutz Donnerhacke <lutz@donnerhacke.de> (man page)

BUGS
     Error handling for	memory issues is missing.  If kernel memory cannot be
     allocated immediately, a kernel panic will	be triggered.  Same happens if
     an	mbuf is	fragmented within the transport	headers.

FreeBSD	13.0		       October 17, 2019			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | HOOKS | MODE OF OPERATION | CONTROL MESSAGES | SHUTDOWN | EXAMPLES | SEE ALSO | AUTHORS | BUGS

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

home | help