1.\" Copyright (c) 2010 Maxim Ignatenko <gelraen.ua@gmail.com> 2.\" Copyright (c) 2010 Vadim Goncharov <vadimnuclight@tpu.ru> 3.\" Copyright (c) 2015 Dmitry Vagin <daemon.hammer@ya.ru> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" $FreeBSD$ 28.\" 29.Dd November 17, 2015 30.Dt NG_PATCH 4 31.Os 32.Sh NAME 33.Nm ng_patch 34.Nd "trivial mbuf data modifying netgraph node type" 35.Sh SYNOPSIS 36.In netgraph/ng_patch.h 37.Sh DESCRIPTION 38The 39.Nm patch 40node performs data modification of packets passing through it. 41Modifications are restricted to a subset of C language operations 42on unsigned integers of 8, 16, 32 or 64 bit size. 43These are: set to new value (=), addition (+=), subtraction (-=), 44multiplication (*=), division (/=), negation (= -), 45bitwise AND (&=), bitwise OR (|=), bitwise eXclusive OR (^=), 46shift left (<<=), shift right (>>=). 47A negation operation is the one exception: integer is treated as signed 48and second operand (the 49.Va value ) 50is not used. 51If there is more than one modification operation, they are applied 52to packets sequentially in the order they were specified by the user. 53The data payload of a packet is viewed as an array of bytes, with a zero offset 54corresponding to the very first byte of packet headers, and the 55.Va length 56bytes beginning from 57.Va offset 58as a single integer in network byte order. 59An additional offset can be optionally 60requested at configuration time to account for packet type. 61.Sh HOOKS 62This node type has two hooks: 63.Bl -tag -width ".Va out" 64.It Va in 65Packets received on this hook are modified according to rules specified 66in the configuration and then forwarded to the 67.Ar out 68hook, if it exists. 69Otherwise they are reflected back to the 70.Ar in 71hook. 72.It Va out 73Packets received on this hook are forwarded to the 74.Ar in 75hook without any changes. 76.El 77.Sh CONTROL MESSAGES 78This node type supports the generic control messages, plus the following: 79.Bl -tag -width foo 80.It Dv NGM_PATCH_SETDLT Pq Ic setdlt 81Sets the data link type on the 82.Va in 83hook (to help calculate relative offset). Currently, supported types are 84.Cm DLT_RAW 85(raw IP datagrams , no offset applied, the default) and 86.Cm DLT_EN10MB 87(Ethernet). DLT_ definitions can be found in 88.In net/bpf.h . 89If you want to work on the link layer header you must use no additional offset by specifying 90.Cm DLT_RAW . 91If 92.Cm EN10MB 93is specified, then the optional additional offset will take into account the Ethernet header and a QinQ header if present. 94.It Dv NGM_PATCH_GETDLT Pq Ic getdlt 95This control message returns the data link type of the 96.Va in 97hook. 98.It Dv NGM_PATCH_SETCONFIG Pq Ic setconfig 99This command sets the sequence of modify operations 100that will be applied to incoming data on a hook. 101The following 102.Vt "struct ng_patch_config" 103must be supplied as an argument: 104.Bd -literal -offset 4n 105struct ng_patch_op { 106 uint32_t offset; 107 uint16_t length; /* 1,2,4 or 8 bytes */ 108 uint16_t mode; 109 uint64_t value; 110}; 111/* Patching modes */ 112#define NG_PATCH_MODE_SET 1 113#define NG_PATCH_MODE_ADD 2 114#define NG_PATCH_MODE_SUB 3 115#define NG_PATCH_MODE_MUL 4 116#define NG_PATCH_MODE_DIV 5 117#define NG_PATCH_MODE_NEG 6 118#define NG_PATCH_MODE_AND 7 119#define NG_PATCH_MODE_OR 8 120#define NG_PATCH_MODE_XOR 9 121#define NG_PATCH_MODE_SHL 10 122#define NG_PATCH_MODE_SHR 11 123 124struct ng_patch_config { 125 uint32_t count; 126 uint32_t csum_flags; 127 uint32_t relative_offset; 128 struct ng_patch_op ops[]; 129}; 130.Ed 131.Pp 132The 133.Va csum_flags 134can be set to any combination of CSUM_IP, CSUM_TCP, CSUM_SCTP and CSUM_UDP 135(other values are ignored) for instructing the IP stack to recalculate the 136corresponding checksum before transmitting packet on output interface. 137The 138.Nm 139node does not do any checksum correction by itself. 140.It Dv NGM_PATCH_GETCONFIG Pq Ic getconfig 141This control message returns the current set of modify operations, 142in the form of a 143.Vt "struct ng_patch_config" . 144.It Dv NGM_PATCH_GET_STATS Pq Ic getstats 145Returns the node's statistics as a 146.Vt "struct ng_patch_stats" . 147.It Dv NGM_PATCH_CLR_STATS Pq Ic clrstats 148Clears the node's statistics. 149.It Dv NGM_PATCH_GETCLR_STATS Pq Ic getclrstats 150This command is identical to 151.Dv NGM_PATCH_GET_STATS , 152except that the statistics are also atomically cleared. 153.El 154.Sh SHUTDOWN 155This node shuts down upon receipt of a 156.Dv NGM_SHUTDOWN 157control message, or when all hooks have been disconnected. 158.Sh EXAMPLES 159This 160.Nm 161node was designed to modify TTL and TOS/DSCP fields in IP packets. 162As an example, 163suppose you have two adjacent simplex links to a remote network 164(e.g.\& satellite), so that the packets expiring in between 165will generate unwanted ICMP-replies which have to go forth, not back. 166Thus you need to raise TTL of every packet entering link by 2 167to ensure the TTL will not reach zero there. 168To achieve this you can set an 169.Xr ipfw 8 170rule to use the 171.Cm netgraph 172action to inject packets which are going to the simplex link into the patch node, by using the 173following 174.Xr ngctl 8 175script: 176.Bd -literal -offset 4n 177/usr/sbin/ngctl -f- <<-SEQ 178 mkpeer ipfw: patch 200 in 179 name ipfw:200 ttl_add 180 msg ttl_add: setconfig { count=1 csum_flags=1 ops=[ \e 181 { mode=2 value=3 length=1 offset=8 } ] } 182SEQ 183/sbin/ipfw add 150 netgraph 200 ip from any to simplex.remote.net 184.Ed 185.Pp 186Here the 187.Dq Li ttl_add 188node of type 189.Nm 190is configured to add (mode 191.Dv NG_PATCH_MODE_ADD ) 192a 193.Va value 194of 3 to a one-byte TTL field, which is 9th byte of IP packet header. 195.Pp 196Another example would be two consecutive modifications of packet TOS 197field: say, you need to clear the 198.Dv IPTOS_THROUGHPUT 199bit and set the 200.Dv IPTOS_MINCOST 201bit. 202So you do: 203.Bd -literal -offset 4n 204/usr/sbin/ngctl -f- <<-SEQ 205 mkpeer ipfw: patch 300 in 206 name ipfw:300 tos_chg 207 msg tos_chg: setconfig { count=2 csum_flags=1 ops=[ \e 208 { mode=7 value=0xf7 length=1 offset=1 } \e 209 { mode=8 value=0x02 length=1 offset=1 } ] } 210SEQ 211/sbin/ipfw add 160 netgraph 300 ip from any to any not dst-port 80 212.Ed 213.Pp 214This first does 215.Dv NG_PATCH_MODE_AND 216clearing the fourth bit and then 217.Dv NG_PATCH_MODE_OR 218setting the third bit. 219.Pp 220In both examples the 221.Va csum_flags 222field indicates that IP checksum (but not TCP or UDP checksum) should be 223recalculated before transmit. 224.Pp 225Note: one should ensure that packets are returned to ipfw after processing 226inside 227.Xr netgraph 4 , 228by setting appropriate 229.Xr sysctl 8 230variable: 231.Bd -literal -offset 4n 232sysctl net.inet.ip.fw.one_pass=0 233.Ed 234.Sh SEE ALSO 235.Xr netgraph 4 , 236.Xr ng_ipfw 4 , 237.Xr ngctl 8 238.Sh HISTORY 239The 240.Nm 241node type was implemented in 242.Fx 8.1 . 243.Sh AUTHORS 244.An "Maxim Ignatenko" Aq gelraen.ua@gmail.com . 245.Pp 246Relative offset code by 247.An "DMitry Vagin" 248.Pp 249This manual page was written by 250.An "Vadim Goncharov" Aq vadimnuclight@tpu.ru . 251.Sh BUGS 252The node blindly tries to apply every patching operation to each packet 253(except those which offset if greater than length of the packet), 254so be sure that you supply only the right packets to it (e.g. changing 255bytes in the ARP packets meant to be in IP header could corrupt 256them and make your machine unreachable from the network). 257.Pp 258.Em !!! WARNING !!! 259.Pp 260The output path of the IP stack assumes correct fields and lengths in the 261packets - changing them by to incorrect values can cause 262unpredictable results including kernel panics. 263