Provided by: freebsd-manpages_8.2-1_all bug

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
     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 offset corresponding to the very first byte of packet
     headers, and length bytes beginning from offset are taken as a single
     integer in network byte order.

HOOKS

     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.

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 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.

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 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 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
     processing 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
     unpredictable results including kernel panics.