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..4937327
--- /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 June 9, 2010
+.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 indent
+.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 indent
+.It Dv NGM_PATCH_SETCONFIG Pq Li 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 Li getconfig
+This control message obtains current set of modify operations,
+returned as
+.Vt "struct ng_patch_config" .
+.It Dv NGM_PATCH_GET_STATS Pq Li getstats
+Returns node statistics as a
+.Vt "struct ng_patch_stats" .
+.It Dv NGM_PATCH_CLR_STATS Pq Li clrstats
+Clear node statistics.
+.It Dv NGM_PATCH_GETCLR_STATS Pq Li 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 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 600 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.