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

FreeBSD Manual Pages


home | help
NG_PATCH(4)		 BSD Kernel Interfaces Manual		   NG_PATCH(4)

     ng_patch -- trivial mbuf data modifying netgraph node type

     #include <netgraph/ng_patch.h>

     The patch node performs data modification of packets passing through it.
     Modifications are restricted to a subset of C language operations on un-
     signed 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	eXclusive 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 specified by
     user.  Data payload of packet is viewed as	array of bytes,	with zero off-
     set corresponding to the very first byte of packet	headers, and length
     bytes beginning from offset are taken as a	single integer in network byte

     This node type has	two hooks:

     in	     Packets received on this hook are modified	according to rules
	     specified in config and then forwarded to out hook, if it exists
	     and connected.  Otherwise they are	reflected back to the in hook.

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

     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 check-
	     sum before	transmitting 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.

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

     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. sat-
     ellite), 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)

	 /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 } ]	}
	 /sbin/ipfw add	150 netgraph 200 ip from any to

     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 } ] }
	 /sbin/ipfw add	160 netgraph 600 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

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

     The ng_patch node type was	implemented in FreeBSD 8.1.

     Maxim Ignatenko <>.  This manual page was written by
     Vadim Goncharov <>.

     Node blindly tries	to apply every patching	operation to each packet (ex-
     cept 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 ma-
     chine 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.

BSD				 June 9, 2010				   BSD


Want to link to this manual page? Use this URL:

home | help