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