share/man/man4/ng_patch.4

   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
  37 The
  38 .Nm patch
  39 node performs data modification of packets passing through it.
  40 Modifications are restricted to a subset of C language operations
  41 on unsigned integers of 8, 16, 32 or 64 bit size.
  42 These are: set to new value (=), addition (+=), subtraction (-=),
  43 multiplication (*=), division (/=), negation (= -),
  44 bitwise AND (&=), bitwise OR (|=), bitwise eXclusive OR (^=),
  45 shift left (<<=), shift right (>>=).
  46 A negation operation is the one exception: integer is treated as signed
  47 and second operand (the
  48 .Va value )
  49 is not used.
  50 There may be several modification operations, they are all applied
  51 to a packet sequentially in order they were specified by user.
  52 Data payload of packet is viewed as array of bytes, with zero offset
  53 corresponding to the very first byte of packet headers, and
  54 .Va length
  55 bytes beginning from
  56 .Va offset
  57 are taken as a single integer in network byte order.
  58 .Sh HOOKS
  59 This node type has two hooks:
  60 .Bl -tag -width ".Va out"
  61 .It Va in
  62 Packets received on this hook are modified according to rules specified
  63 in config and then forwarded to
  64 .Ar out
  65 hook, if it exists and connected.
  66 Otherwise they are reflected back to the
  67 .Ar in
  68 hook.
  69 .It Va out
  70 Packets received on this hook are forwarded to
  71 .Ar in
  72 hook without any changes.
  73 .El
  74 .Sh CONTROL MESSAGES
  75 This node type supports the generic control messages, plus the following:
  76 .Bl -tag -width foo
  77 .It Dv NGM_PATCH_SETCONFIG Pq Ic setconfig
  78 This command sets the sequence of modify operations
  79 that will be applied to incoming data on a hook.
  80 The following
  81 .Vt "struct ng_patch_config"
  82 must be supplied as an argument:
  83 .Bd -literal -offset 4n
  84 struct 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
 103 struct ng_patch_config {
 104         uint32_t        count;
 105         uint32_t        csum_flags;
 106         struct ng_patch_op ops[];
 107 };
 108 .Ed
 109 .Pp
 110 The
 111 .Va csum_flags
 112 can 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
 114 corresponding checksum before transmitting packet on output interface.
 115 The
 116 .Nm
 117 node does not do any checksum correction by itself.
 118 .It Dv NGM_PATCH_GETCONFIG Pq Ic getconfig
 119 This control message obtains current set of modify operations,
 120 returned as
 121 .Vt "struct ng_patch_config" .
 122 .It Dv NGM_PATCH_GET_STATS Pq Ic getstats
 123 Returns node statistics as a
 124 .Vt "struct ng_patch_stats" .
 125 .It Dv NGM_PATCH_CLR_STATS Pq Ic clrstats
 126 Clear node statistics.
 127 .It Dv NGM_PATCH_GETCLR_STATS Pq Ic getclrstats
 128 This command is identical to
 129 .Dv NGM_PATCH_GET_STATS ,
 130 except that the statistics are also atomically cleared.
 131 .El
 132 .Sh SHUTDOWN
 133 This node shuts down upon receipt of a
 134 .Dv NGM_SHUTDOWN
 135 control message, or when all hooks have been disconnected.
 136 .Sh EXAMPLES
 137 The
 138 .Nm
 139 node allows to modify TTL and TOS/DSCP fields in IP packets.
 140 Suppose you have two adjacent simplex links to remote network
 141 (e.g.\& satellite), so that the packets expiring in between
 142 will generate unwanted ICMP-replies which have to go forth, not back.
 143 Thus you need to raise TTL of every packet entering link by 2
 144 to ensure the TTL will not reach zero there.
 145 So you setup
 146 .Xr ipfw 8
 147 rule with
 148 .Cm netgraph
 149 action to inject packets going to other end of simplex link by the
 150 following
 151 .Xr ngctl 8
 152 script:
 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 } ] }
 159 SEQ
 160 /sbin/ipfw add 150 netgraph 200 ip from any to simplex.remote.net
 161 .Ed
 162 .Pp
 163 Here
 164 .Dq Li ttl_add
 165 node of type
 166 .Nm
 167 configured to add (mode
 168 .Dv NG_PATCH_MODE_ADD )
 169 a
 170 .Va value
 171 of 3 to a one-byte TTL field, which is 9th byte of IP packet header.
 172 .Pp
 173 Another example would be two consecutive modifications of packet TOS
 174 field: say, you need to clear the
 175 .Dv IPTOS_THROUGHPUT
 176 bit and set the
 177 .Dv IPTOS_MINCOST
 178 bit.
 179 So 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 } ] }
 187 SEQ
 188 /sbin/ipfw add 160 netgraph 300 ip from any to any not dst-port 80
 189 .Ed
 190 .Pp
 191 This first does
 192 .Dv NG_PATCH_MODE_AND
 193 clearing the fourth bit and then
 194 .Dv NG_PATCH_MODE_OR
 195 setting the third bit.
 196 .Pp
 197 In both examples the
 198 .Va csum_flags
 199 field indicates that IP checksum (but not TCP or UDP checksum) should be
 200 recalculated before transmit.
 201 .Pp
 202 Note: one should ensure that packets are returned to ipfw after processing
 203 inside
 204 .Xr netgraph 4 ,
 205 by setting appropriate
 206 .Xr sysctl 8
 207 variable:
 208 .Bd -literal -offset 4n
 209 sysctl 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
 216 The
 217 .Nm
 218 node type was implemented in
 219 .Fx 8.1 .
 220 .Sh AUTHORS
 221 .An "Maxim Ignatenko" Aq gelraen.ua@gmail.com .
 222 This manual page was written by
 223 .An "Vadim Goncharov" Aq vadimnuclight@tpu.ru .
 224 .Sh BUGS
 225 Node blindly tries to apply every patching operation to each packet
 226 (except those which offset if greater than length of the packet),
 227 so be sure that you supply only the right packets to it (e.g. changing
 228 bytes in the ARP packets meant to be in IP header could corrupt
 229 them and make your machine unreachable from the network).
 230 .Pp
 231 .Em !!! WARNING !!!
 232 .Pp
 233 Output path of the IP stack assumes correct fields and lengths in the
 234 packets - changing them by mistake to incorrect values can cause
 235 unpredictable results including kernel panics.