freebsd-skq/share/man/man4/ng_patch.4

.\" Copyright (c) 2010 Maxim Ignatenko <gelraen.ua@gmail.com>
.\" Copyright (c) 2010 Vadim Goncharov <vadimnuclight@tpu.ru>
.\" Copyright (c) 2015 Dmitry Vagin <daemon.hammer@ya.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 November 17, 2015
.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.
If there is more than one modification operation, they are applied
to packets sequentially in the order they were specified by the user.
The data payload of a packet is viewed as an array of bytes, with a zero offset
corresponding to the very first byte of packet headers, and the
.Va length
bytes beginning from
.Va offset
as a single integer in network byte order. An additional offset can be optionally 
requested at configuration time to account for packet type.
.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 the configuration and then forwarded to the
.Ar out
hook, if it exists.
Otherwise they are reflected back to the
.Ar in
hook.
.It Va out
Packets received on this hook are forwarded to the
.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_SETDLT Pq Ic setdlt
Sets the data link type on the
.Va in
hook (to help calculate relative offset). Currently, supported types are
.Cm DLT_RAW
(raw IP datagrams , no offset applied, the default) and
.Cm DLT_EN10MB
(Ethernet). DLT_ definitions can be found in
.In net/bpf.h .
If you want to work on the link layer header you must use no additional offset by specifying
.Cm DLT_RAW .
If
.Cm EN10MB 
is specified, then the optional additional offset will take into account the Ethernet header and a QinQ header if present.
.It Dv NGM_PATCH_GETDLT Pq Ic getdlt
This control message returns the data link type of the
.Va in
hook.
.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 {
	uint32_t	offset;
	uint16_t	length; /* 1,2,4 or 8 bytes */
	uint16_t	mode;
	uint64_t	value;
};
/* 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;
	uint32_t	relative_offset;
	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 returns the current set of modify operations,
in the form of a
.Vt "struct ng_patch_config" .
.It Dv NGM_PATCH_GET_STATS Pq Ic getstats
Returns the node's statistics as a
.Vt "struct ng_patch_stats" .
.It Dv NGM_PATCH_CLR_STATS Pq Ic clrstats
Clears the node's 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
This
.Nm
node was designed to modify TTL and TOS/DSCP fields in IP packets.
As an example,
suppose you have two adjacent simplex links to a 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.
To achieve this you can set an
.Xr ipfw 8
rule to use the
.Cm netgraph
action to inject packets which are going to the simplex link into the patch node, by using 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 the
.Dq Li ttl_add
node of type
.Nm
is 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 .
.Pp
Relative offset code by
.An "DMitry Vagin"
.Pp
This manual page was written by
.An "Vadim Goncharov" Aq vadimnuclight@tpu.ru .
.Sh BUGS
The 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
The output path of the IP stack assumes correct fields and lengths in the
packets - changing them by to incorrect values can cause
unpredictable results including kernel panics.