--- name: "ng_patch" section: "4freebsd" platform: "linux" package: "freebsd-manpages" version: "12.2-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/ng_patch/4freebsd" --- # ng\_patch(4freebsd) trivial mbuf data modifying netgraph node type ## NAME **ng\_patch** – trivial mbuf data modifying netgraph node type ## SYNOPSIS **#include \** ## 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. If there is more than one modification operation, they are applied to packets sequentially in the order they were specified by the user. The data payload of a packet is viewed as an array of bytes, with a zero offset corresponding to the very first byte of packet headers, and the *length* bytes beginning from *offset* as a single integer in network byte order. An additional offset can be optionally requested at configuration time to account for packet type. ## HOOKS This node type has two hooks: - *in* Packets received on this hook are modified according to rules specified in the configuration and then forwarded to the *out* hook, if it exists. Otherwise they are reflected back to the *in* hook. - *out* Packets received on this hook are forwarded to the *in* hook without any changes. ## CONTROL MESSAGES This node type supports the generic control messages, plus the following: - NGM\_PATCH\_SETDLT (**setdlt**) Sets the data link type on the *in* hook (to help calculate relative offset). Currently, supported types are **DLT\_RAW** (raw IP datagrams , no offset applied, the default) and **DLT\_EN10MB** (Ethernet). DLT\_ definitions can be found in ⟨net/bpf.h⟩. If you want to work on the link layer header you must use no additional offset by specifying **DLT\_RAW**. If **EN10MB** is specified, then the optional additional offset will take into account the Ethernet header and a QinQ header if present. - NGM\_PATCH\_GETDLT (**getdlt**) This control message returns the data link type of the *in* hook. - 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 { uint32_t offset; uint16_t length; /* 1,2,4 or 8 bytes */ uint16_t mode; uint64_t value; }; /* 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; uint32_t relative_offset; 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 returns the current set of modify operations, in the form of a *struct ng\_patch\_config*. - NGM\_PATCH\_GET\_STATS (**getstats**) Returns the node's statistics as a *struct ng\_patch\_stats*. - NGM\_PATCH\_CLR\_STATS (**clrstats**) Clears the node's 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 This **ng\_patch** node was designed to modify TTL and TOS/DSCP fields in IP packets. As an example, suppose you have two adjacent simplex links to a 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. To achieve this you can set an [ipfw(8)](/ipfw/8.md) rule to use the **netgraph** action to inject packets which are going to the simplex link into the patch node, by using the following [ngctl(8)](/ngctl/8.md) 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 the “ttl\_add” node of type **ng\_patch** is 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 processing inside [netgraph(4)](/netgraph/4.md), by setting appropriate [sysctl(8)](/sysctl/8.md) variable: ``` sysctl net.inet.ip.fw.one_pass=0 ``` ## SEE ALSO [netgraph(4)](/netgraph/4.md), [ng\_ipfw(4)](/ng_ipfw/4.md), [ngctl(8)](/ngctl/8.md) ## HISTORY The **ng\_patch** node type was implemented in FreeBSD 8.1. ## AUTHORS Maxim Ignatenko ⟨gelraen.ua@gmail.com⟩. Relative offset code by DMitry Vagin This manual page was written by Vadim Goncharov ⟨vadimnuclight@tpu.ru⟩. ## BUGS The 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* *!!!* The output path of the IP stack assumes correct fields and lengths in the packets - changing them by to incorrect values can cause unpredictable results including kernel panics.