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_PATCH(4)	       FreeBSD Kernel Interfaces Manual		   NG_PATCH(4)

NAME
     ng_patch -- trivial mbuf data modifying netgraph node type

SYNOPSIS
     #include <netgraph/ng_patch.h>

DESCRIPTION
     The patch node performs data modification of packets passing through it.
     Modifications are restricted to a subset of C language operations on
     unsigned integers of 8, 16, 32 or 64 bit size.  These are:	set to new
     value (=),	addition (+=), subtraction (-=), multiplication	(*=), division
     (/=), negation (= -), bitwise AND (&=), bitwise OR	(|=), bitwise eXclu-
     sive OR (^=), shift left (<<=), shift right (>>=).	 A negation operation
     is	the one	exception: integer is treated as signed	and second operand
     (the value) is not	used.  There may be several modification operations,
     they are all applied to a packet sequentially in order they were speci-
     fied by user.  Data payload of packet is viewed as	array of bytes,	with
     zero offset corresponding to the very first byte of packet	headers, and
     length bytes beginning from offset	are taken as a single integer in net-
     work byte order.

HOOKS
     This node type has	two hooks:

     in	  Packets received on this hook	are modified according to rules	speci-
	  fied in config and then forwarded to out hook, if it exists and con-
	  nected.  Otherwise they are reflected	back to	the in hook.

     out  Packets received on this hook	are forwarded to in hook without any
	  changes.

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

     NGM_PATCH_SETCONFIG (setconfig)
	  This command sets the	sequence of modify operations that will	be
	  applied to incoming data on a	hook.  The following struct
	  ng_patch_config must be supplied as an argument:

	      struct ng_patch_op {
		      uint64_t	      value;
		      uint32_t	      offset;
		      uint16_t	      length; /* 1,2,4 or 8 bytes */
		      uint16_t	      mode;
	      };
	      /* Patching modes	*/
	      #define NG_PATCH_MODE_SET	      1
	      #define NG_PATCH_MODE_ADD	      2
	      #define NG_PATCH_MODE_SUB	      3
	      #define NG_PATCH_MODE_MUL	      4
	      #define NG_PATCH_MODE_DIV	      5
	      #define NG_PATCH_MODE_NEG	      6
	      #define NG_PATCH_MODE_AND	      7
	      #define NG_PATCH_MODE_OR	      8
	      #define NG_PATCH_MODE_XOR	      9
	      #define NG_PATCH_MODE_SHL	      10
	      #define NG_PATCH_MODE_SHR	      11

	      struct ng_patch_config {
		      uint32_t	      count;
		      uint32_t	      csum_flags;
		      struct ng_patch_op ops[];
	      };

	  The csum_flags can be	set to any combination of CSUM_IP, CSUM_TCP,
	  CSUM_SCTP and	CSUM_UDP (other	values are ignored) for	instructing
	  the IP stack to recalculate the corresponding	checksum before	trans-
	  mitting packet on output interface.  The ng_patch node does not do
	  any checksum correction by itself.

     NGM_PATCH_GETCONFIG (getconfig)
	  This control message obtains current set of modify operations,
	  returned as struct ng_patch_config.

     NGM_PATCH_GET_STATS (getstats)
	  Returns node statistics as a struct ng_patch_stats.

     NGM_PATCH_CLR_STATS (clrstats)
	  Clear	node statistics.

     NGM_PATCH_GETCLR_STATS (getclrstats)
	  This command is identical to NGM_PATCH_GET_STATS, except that	the
	  statistics are also atomically cleared.

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

EXAMPLES
     The ng_patch node allows to modify	TTL and	TOS/DSCP fields	in IP packets.
     Suppose you have two adjacent simplex links to remote network (e.g.
     satellite), so that the packets expiring in between will generate
     unwanted ICMP-replies which have to go forth, not back.  Thus you need to
     raise TTL of every	packet entering	link by	2 to ensure the	TTL will not
     reach zero	there.	So you setup ipfw(8) rule with netgraph	action to
     inject packets going to other end of simplex link by the following
     ngctl(8) script:

	 /usr/sbin/ngctl -f- <<-SEQ
		 mkpeer	ipfw: patch 200	in
		 name ipfw:200 ttl_add
		 msg ttl_add: setconfig	{ count=1 csum_flags=1 ops=[	 \
			 { mode=2 value=3 length=1 offset=8 } ]	}
	 SEQ
	 /sbin/ipfw add	150 netgraph 200 ip from any to	simplex.remote.net

     Here ``ttl_add'' node of type ng_patch configured to add (mode
     NG_PATCH_MODE_ADD)	a value	of 3 to	a one-byte TTL field, which is 9th
     byte of IP	packet header.

     Another example would be two consecutive modifications of packet TOS
     field: say, you need to clear the IPTOS_THROUGHPUT	bit and	set the
     IPTOS_MINCOST bit.	 So you	do:

	 /usr/sbin/ngctl -f- <<-SEQ
		 mkpeer	ipfw: patch 300	in
		 name ipfw:300 tos_chg
		 msg tos_chg: setconfig	{ count=2 csum_flags=1 ops=[	 \
			 { mode=7 value=0xf7 length=1 offset=1 }	 \
			 { mode=8 value=0x02 length=1 offset=1 } ] }
	 SEQ
	 /sbin/ipfw add	160 netgraph 300 ip from any to	any not	dst-port 80

     This first	does NG_PATCH_MODE_AND clearing	the fourth bit and then
     NG_PATCH_MODE_OR setting the third	bit.

     In	both examples the csum_flags field indicates that IP checksum (but not
     TCP or UDP	checksum) should be recalculated before	transmit.

     Note: one should ensure that packets are returned to ipfw after process-
     ing inside	netgraph(4), by	setting	appropriate sysctl(8) variable:

	 sysctl	net.inet.ip.fw.one_pass=0

SEE ALSO
     netgraph(4), ng_ipfw(4), ngctl(8)

HISTORY
     The ng_patch node type was	implemented in FreeBSD 8.1.

AUTHORS
     Maxim Ignatenko <gelraen.ua@gmail.com>.  This manual page was written by
     Vadim Goncharov <vadimnuclight@tpu.ru>.

BUGS
     Node blindly tries	to apply every patching	operation to each packet
     (except those which offset	if greater than	length of the packet), so be
     sure that you supply only the right packets to it (e.g. changing bytes in
     the ARP packets meant to be in IP header could corrupt them and make your
     machine unreachable from the network).

     !!! WARNING !!!

     Output path of the	IP stack assumes correct fields	and lengths in the
     packets - changing	them by	mistake	to incorrect values can	cause unpre-
     dictable results including	kernel panics.

FreeBSD	9.3			 March 5, 2012			   FreeBSD 9.3

NAME | SYNOPSIS | DESCRIPTION | HOOKS | CONTROL MESSAGES | SHUTDOWN | EXAMPLES | SEE ALSO | HISTORY | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=ng_patch&manpath=FreeBSD+10.0-RELEASE>

home | help