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