diff options
Diffstat (limited to 'share/man/man4/ng_patch.4')
-rw-r--r-- | share/man/man4/ng_patch.4 | 235 |
1 files changed, 235 insertions, 0 deletions
diff --git a/share/man/man4/ng_patch.4 b/share/man/man4/ng_patch.4 new file mode 100644 index 0000000..db7ede54 --- /dev/null +++ b/share/man/man4/ng_patch.4 @@ -0,0 +1,235 @@ +.\" Copyright (c) 2010 Maxim Ignatenko <gelraen.ua@gmail.com> +.\" Copyright (c) 2010 Vadim Goncharov <vadimnuclight@tpu.ru> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd March 5, 2012 +.Dt NG_PATCH 4 +.Os +.Sh NAME +.Nm ng_patch +.Nd "trivial mbuf data modifying netgraph node type" +.Sh SYNOPSIS +.In netgraph/ng_patch.h +.Sh DESCRIPTION +The +.Nm patch +node performs data modification of packets passing through it. +Modifications are restricted to a subset of C language operations +on unsigned integers of 8, 16, 32 or 64 bit size. +These are: set to new value (=), addition (+=), subtraction (-=), +multiplication (*=), division (/=), negation (= -), +bitwise AND (&=), bitwise OR (|=), bitwise eXclusive OR (^=), +shift left (<<=), shift right (>>=). +A negation operation is the one exception: integer is treated as signed +and second operand (the +.Va value ) +is not used. +There may be several modification operations, they are all applied +to a packet sequentially in order they were specified by user. +Data payload of packet is viewed as array of bytes, with zero offset +corresponding to the very first byte of packet headers, and +.Va length +bytes beginning from +.Va offset +are taken as a single integer in network byte order. +.Sh HOOKS +This node type has two hooks: +.Bl -tag -width ".Va out" +.It Va in +Packets received on this hook are modified according to rules specified +in config and then forwarded to +.Ar out +hook, if it exists and connected. +Otherwise they are reflected back to the +.Ar in +hook. +.It Va out +Packets received on this hook are forwarded to +.Ar in +hook without any changes. +.El +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width foo +.It Dv NGM_PATCH_SETCONFIG Pq Ic setconfig +This command sets the sequence of modify operations +that will be applied to incoming data on a hook. +The following +.Vt "struct ng_patch_config" +must be supplied as an argument: +.Bd -literal -offset 4n +struct ng_patch_op { + uint64_t value; + uint32_t offset; + uint16_t length; /* 1,2,4 or 8 bytes */ + uint16_t mode; +}; +/* Patching modes */ +#define NG_PATCH_MODE_SET 1 +#define NG_PATCH_MODE_ADD 2 +#define NG_PATCH_MODE_SUB 3 +#define NG_PATCH_MODE_MUL 4 +#define NG_PATCH_MODE_DIV 5 +#define NG_PATCH_MODE_NEG 6 +#define NG_PATCH_MODE_AND 7 +#define NG_PATCH_MODE_OR 8 +#define NG_PATCH_MODE_XOR 9 +#define NG_PATCH_MODE_SHL 10 +#define NG_PATCH_MODE_SHR 11 + +struct ng_patch_config { + uint32_t count; + uint32_t csum_flags; + struct ng_patch_op ops[]; +}; +.Ed +.Pp +The +.Va csum_flags +can be set to any combination of CSUM_IP, CSUM_TCP, CSUM_SCTP and CSUM_UDP +(other values are ignored) for instructing the IP stack to recalculate the +corresponding checksum before transmitting packet on output interface. +The +.Nm +node does not do any checksum correction by itself. +.It Dv NGM_PATCH_GETCONFIG Pq Ic getconfig +This control message obtains current set of modify operations, +returned as +.Vt "struct ng_patch_config" . +.It Dv NGM_PATCH_GET_STATS Pq Ic getstats +Returns node statistics as a +.Vt "struct ng_patch_stats" . +.It Dv NGM_PATCH_CLR_STATS Pq Ic clrstats +Clear node statistics. +.It Dv NGM_PATCH_GETCLR_STATS Pq Ic getclrstats +This command is identical to +.Dv NGM_PATCH_GET_STATS , +except that the statistics are also atomically cleared. +.El +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when all hooks have been disconnected. +.Sh EXAMPLES +The +.Nm +node allows to modify TTL and TOS/DSCP fields in IP packets. +Suppose you have two adjacent simplex links to remote network +(e.g.\& satellite), so that the packets expiring in between +will generate unwanted ICMP-replies which have to go forth, not back. +Thus you need to raise TTL of every packet entering link by 2 +to ensure the TTL will not reach zero there. +So you setup +.Xr ipfw 8 +rule with +.Cm netgraph +action to inject packets going to other end of simplex link by the +following +.Xr ngctl 8 +script: +.Bd -literal -offset 4n +/usr/sbin/ngctl -f- <<-SEQ + mkpeer ipfw: patch 200 in + name ipfw:200 ttl_add + msg ttl_add: setconfig { count=1 csum_flags=1 ops=[ \e + { mode=2 value=3 length=1 offset=8 } ] } +SEQ +/sbin/ipfw add 150 netgraph 200 ip from any to simplex.remote.net +.Ed +.Pp +Here +.Dq Li ttl_add +node of type +.Nm +configured to add (mode +.Dv NG_PATCH_MODE_ADD ) +a +.Va value +of 3 to a one-byte TTL field, which is 9th byte of IP packet header. +.Pp +Another example would be two consecutive modifications of packet TOS +field: say, you need to clear the +.Dv IPTOS_THROUGHPUT +bit and set the +.Dv IPTOS_MINCOST +bit. +So you do: +.Bd -literal -offset 4n +/usr/sbin/ngctl -f- <<-SEQ + mkpeer ipfw: patch 300 in + name ipfw:300 tos_chg + msg tos_chg: setconfig { count=2 csum_flags=1 ops=[ \e + { mode=7 value=0xf7 length=1 offset=1 } \e + { mode=8 value=0x02 length=1 offset=1 } ] } +SEQ +/sbin/ipfw add 160 netgraph 300 ip from any to any not dst-port 80 +.Ed +.Pp +This first does +.Dv NG_PATCH_MODE_AND +clearing the fourth bit and then +.Dv NG_PATCH_MODE_OR +setting the third bit. +.Pp +In both examples the +.Va csum_flags +field indicates that IP checksum (but not TCP or UDP checksum) should be +recalculated before transmit. +.Pp +Note: one should ensure that packets are returned to ipfw after processing +inside +.Xr netgraph 4 , +by setting appropriate +.Xr sysctl 8 +variable: +.Bd -literal -offset 4n +sysctl net.inet.ip.fw.one_pass=0 +.Ed +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ng_ipfw 4 , +.Xr ngctl 8 +.Sh HISTORY +The +.Nm +node type was implemented in +.Fx 8.1 . +.Sh AUTHORS +.An "Maxim Ignatenko" Aq gelraen.ua@gmail.com . +This manual page was written by +.An "Vadim Goncharov" Aq vadimnuclight@tpu.ru . +.Sh BUGS +Node blindly tries to apply every patching operation to each packet +(except those which offset if greater than length of the packet), +so be sure that you supply only the right packets to it (e.g. changing +bytes in the ARP packets meant to be in IP header could corrupt +them and make your machine unreachable from the network). +.Pp +.Em !!! WARNING !!! +.Pp +Output path of the IP stack assumes correct fields and lengths in the +packets - changing them by mistake to incorrect values can cause +unpredictable results including kernel panics. |