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